diff --git a/extlib/README b/extlib/README new file mode 100644 index 0000000000..cfc2f9c8c4 --- /dev/null +++ b/extlib/README @@ -0,0 +1,58 @@ +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. + +FAQ: + +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 StatusNet 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 StatusNet_* 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.