From 39845444cc0baed11b575d50e4c48d7c7a15ab9b Mon Sep 17 00:00:00 2001 From: Diogo Cordeiro Date: Wed, 10 Jul 2019 19:36:30 +0100 Subject: [PATCH] [DOCUMENTATION] Update description of extlib and vendor directories --- extlib/README | 106 -------------------------------------------- extlib/README.md | 39 ++++++++++++++++ plugins/Xmpp/README | 4 ++ vendor/README.md | 60 +++++++++++++++++++++++++ 4 files changed, 103 insertions(+), 106 deletions(-) delete mode 100644 extlib/README create mode 100644 extlib/README.md create mode 100644 vendor/README.md diff --git a/extlib/README b/extlib/README deleted file mode 100644 index d4be0a1219..0000000000 --- a/extlib/README +++ /dev/null @@ -1,106 +0,0 @@ -DO NOT "FIX" CODE IN THIS DIRECTORY. - -ONLY UPSTREAM VERSIONS OF SOFTWARE GO IN THIS DIRECTORY. - -This directory is provided as a courtesy to our users who might be -unable or unwilling to find and install libraries we depend on. - -If we "fix" software in this directory, we hamstring users who do the -right thing and keep a single version of upstream libraries in a -system-wide library. We introduce subtle and maddening bugs where -our code is "accidentally" using the "wrong" library version. We may -unwittingly interfere with other software that depends on the -canonical release versions of those same libraries! - -Forking upstream software for trivial reasons makes us bad citizens in -the Open Source community and adds unnecessary heartache for our -users. Don't make us "that" project. - -Frequently Asked Questions --------------------------- - -Q: What should we do when we find a bug in upstream software? - -A: First and foremost, REPORT THE BUG, and if possible send in a patch. - - Watch for a release of the upstream software and integrate with it - when it's released. - - In the meantime, work around the bug, if at all possible. Usually, - it's quite possible, if slightly harder or less efficient. - -Q: What if the bug can't be worked around? - -A: If the upstream developers have accepted a bug patch, it's - undesirable but acceptable to apply that patch to the library in - the extlib dir. Ideally, use a release version for upstream or a - version control system snapshot. - - Note that this is a last resort. - -Q: What if upstream is unresponsive or won't accept a patch? - -A: Try again. - -Q: I tried again, and upstream is still unresponsive and nobody's - checked on my patch. Now what? - -A: If the upstream project is moribund and there's a way to adopt it, - propose having the GNU social dev team adopt the project. Or, adopt - it yourself. - -Q: What if there's no upstream authority and it can't be adopted? - -A: Then we fork it. Make a new name and a new version. Include it in - lib/ instead of extlib/, and use the GNUsocial_* prefix to change - the namespace to avoid collisions. - - This is a last resort; consult with the rest of the dev group - before taking this radical step. - -List of external libraries --------------------------- - -A number of external PHP libraries are used to provide basic -functionality and optional functionality for your system. For your -convenience, they are available in the "extlib" directory of this -package, and you do not have to download and install them. However, -you may want to keep them up-to-date with the latest upstream version, -and the URLs are listed here for your convenience. - -- DB_DataObject http://pear.php.net/package/DB_DataObject -- Validate http://pear.php.net/package/Validate -- OpenID by Janrain, http://janrain.com/openid-enabled/ -- PEAR DB. Although this is an older data access system (new - packages should use PDO), the OpenID libraries depend on PEAR DB - or MDB2. -- OAuth.php from http://oauth.googlecode.com/svn/code/php/ - (has been edited to avoid colliding autoload) -- markdown.php from http://michelf.com/projects/php-markdown/ -- PEAR Mail, for sending out mail notifications - http://pear.php.net/package/Mail -- PEAR Net_SMTP, if you use the SMTP factory for notifications - http://pear.php.net/package/Net_SMTP -- PEAR Net_Socket, if you use the SMTP factory for notifications - http://pear.php.net/package/Net_Socket -- XMPPHP, the follow-up to Class.Jabber.php. Probably the best XMPP - library available for PHP. https://github.com/heshanlk/XMPPHP. Note that - as of this writing the version of this library that is available in - the extlib directory is *significantly different* from the upstream - version (patches have been submitted). Upgrading to the upstream - version may render your GNU social site unable to send or receive XMPP - messages. -- Facebook library. Used for the Facebook application. -- PEAR Validate is used for URL and email validation. -- Console_GetOpt for parsing command-line options. -- HTTP_Request2, a library for making HTTP requests. -- PEAR Net_URL2 is an HTTP_Request2 dependency. -- Michelf/Markdown.php Markdown parser library -- Mf2/Parser.php microformats2 parser library - -A design goal of GNU Social is that the basic Web functionality should -work on even the most restrictive commercial hosting services. -However, additional functionality, such as receiving messages by XMPP, -require that you be able to run long-running processes on your account. -In addition, posting by email require that you be able to install a mail -filter in your mail server. diff --git a/extlib/README.md b/extlib/README.md new file mode 100644 index 0000000000..5e10aa568a --- /dev/null +++ b/extlib/README.md @@ -0,0 +1,39 @@ +Most of this directory contents are patched PEAR libraries (necessary as PEAR packages are no longer maintained) + +List of external libraries +-------------------------- + +A number of external PHP libraries are used to provide basic +functionality and optional functionality for your system. For your +convenience, they are available in the "extlib" directory of this +package, and you do not have to download and install them. However, +you may want to keep them up-to-date with the latest upstream version, +and the URLs are listed here for your convenience. + +- DB_DataObject http://pear.php.net/package/DB_DataObject +- Validate http://pear.php.net/package/Validate +- PEAR Mail, for sending out mail notifications + http://pear.php.net/package/Mail +- PEAR Net_SMTP, if you use the SMTP factory for notifications + http://pear.php.net/package/Net_SMTP +- PEAR Net_Socket, if you use the SMTP factory for notifications + http://pear.php.net/package/Net_Socket +- OAuth.php from http://oauth.googlecode.com/svn/code/php/ +(has been edited to avoid colliding autoload) + + +- PEAR Validate is used for URL and email validation. +- Console_GetOpt for parsing command-line options. +- HTTP_Request2, a library for making HTTP requests. +- PEAR Net_URL2 is an HTTP_Request2 dependency. + +TODO +---- + +- Port from PEAR NET to Guzzle +- Port from PEAR DB to Doctrine DBAL +- Port from PEAR mail to PHPMailer +- eventually port OAuth to something more modern + +Why not replace all the components with newer ones? We don't think the alternatives really meet our needs or are at +all necessary and/or better solutions. The code of these patched libraries that we are maintaing is quite good. diff --git a/plugins/Xmpp/README b/plugins/Xmpp/README index 2dbba8372a..9655b009d4 100644 --- a/plugins/Xmpp/README +++ b/plugins/Xmpp/README @@ -56,6 +56,10 @@ Pre-requisites perform on an active site. Using XMPP requires the "imdaemon" to run, since a long-running XMPP connection is somewhat necessary. +A design goal of GNU Social is that the basic Web functionality should +work on even the most restrictive commercial hosting services. +However, additional functionality, such as receiving messages by XMPP, +require that you be able to run long-running processes on your account. Settings ======== diff --git a/vendor/README.md b/vendor/README.md new file mode 100644 index 0000000000..2852d34676 --- /dev/null +++ b/vendor/README.md @@ -0,0 +1,60 @@ +DO NOT "FIX" CODE IN THIS DIRECTORY. + +ONLY UPSTREAM VERSIONS OF SOFTWARE GO IN THIS DIRECTORY. + +This directory is provided as a courtesy to our users who might be +unable or unwilling to find and install libraries we depend on. + +If we "fix" software in this directory, we hamstring users who do the +right thing and keep a single version of upstream libraries in a +system-wide library. We introduce subtle and maddening bugs where +our code is "accidentally" using the "wrong" library version. We may +unwittingly interfere with other software that depends on the +canonical release versions of those same libraries! + +Forking upstream software for trivial reasons makes us bad citizens in +the Open Source community and adds unnecessary heartache for our +users. Don't make us "that" project. + +Frequently Asked Questions +-------------------------- + +Q: What should we do when we find a bug in upstream software? + +A: First and foremost, REPORT THE BUG, and if possible send in a patch. + + Watch for a release of the upstream software and integrate with it + when it's released. + + In the meantime, work around the bug, if at all possible. Usually, + it's quite possible, if slightly harder or less efficient. + +Q: What if the bug can't be worked around? + +A: If the upstream developers have accepted a bug patch, it's + undesirable but acceptable to apply that patch to the library in + the extlib dir. Ideally, use a release version for upstream or a + version control system snapshot. + + Note that this is a last resort. + +Q: What if upstream is unresponsive or won't accept a patch? + +A: Try again. + +Q: I tried again, and upstream is still unresponsive and nobody's + checked on my patch. Now what? + +A: If the upstream project is moribund and there's a way to adopt it, + propose having the GNU social dev team adopt the project. Or, adopt + it yourself. + +Q: What if there's no upstream authority and it can't be adopted? + +A: Then we fork it. Make a new name and a new version. Include it in + extlib/ instead of vendor/, and use the GNUsocial_* prefix to change + the namespace to avoid collisions. + + This is a last resort; consult with the rest of the dev group + before taking this radical step. + -- 2.39.5