+++ /dev/null
-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.
--- /dev/null
+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.
--- /dev/null
+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.
+
projects / quix0rs-gnu-social.git / commitdiff