[DOCUMENTATION] Update description of extlib and vendor directories
This commit is contained in:
Diogo Cordeiro
parent
ec32db2dd6
commit
39845444cc
106
extlib/README
106
extlib/README
|
|
@ -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.
|
|
||||||
39
extlib/README.md
Normal file
39
extlib/README.md
Normal file
|
|
@ -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.
|
||||||
|
|
@ -56,6 +56,10 @@ Pre-requisites
|
||||||
perform on an active site. Using XMPP requires the "imdaemon" to
|
perform on an active site. Using XMPP requires the "imdaemon" to
|
||||||
run, since a long-running XMPP connection is somewhat necessary.
|
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
|
Settings
|
||||||
========
|
========
|
||||||
|
|
|
||||||
60
vendor/README.md
vendored
Normal file
60
vendor/README.md
vendored
Normal file
|
|
@ -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.
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user