127 lines
4.5 KiB
Plaintext
127 lines
4.5 KiB
Plaintext
=========================
|
|
External Library README
|
|
=========================
|
|
|
|
This directory contains two kinds of things: external dependencies
|
|
specified in package.json (which gets installed into the node_modules
|
|
directory), and full copies of third-party code, which we call
|
|
embedded code copies.
|
|
|
|
|
|
External dependencies specified in package.json
|
|
===============================================
|
|
|
|
package.json is a file that specifies external code dependencies. We
|
|
download those using the "npm" tool. As a developer of MediaGoblin,
|
|
install npm however is convenient for you (for example, apt-get
|
|
install npm).
|
|
|
|
If you are "merely installing" MediaGoblin (and aren't attempting to
|
|
change its code), you should know that the MediaGoblin team's main
|
|
release download, also known as the MediaGoblin mulltipack tarball,
|
|
contains a copy of all the code specified via package.json.
|
|
|
|
As a general rule, always specify dependencies in package.json using
|
|
"==" to pin to a specific release that you have tested MediaGoblin
|
|
with. The MediaGoblin team always welcomes patches that merely change
|
|
the version of a dependency so long as you have tested that the app
|
|
works. Doing this is a valuable and significant contribution to the
|
|
project.
|
|
|
|
Other notes about the contents of package.json:
|
|
|
|
* Inconsolata is available in the npm repositories, but it does not
|
|
include the OTF font format, and at the time of writing it appears
|
|
that PIL needs OTF/TTF and cannot accept a WOFF font file. For this
|
|
reason, we have avoided using the Inconsolata package from npm.
|
|
|
|
* Lato is available in NPM as connect-fonts-lato, but the font file
|
|
has a different hash than the file currently in extlib, so we are
|
|
sticking with our extlib version until someone has time to test
|
|
the NPM version. (That could be you!)
|
|
|
|
|
|
Embedded code copies
|
|
====================
|
|
|
|
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 Free Software 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 MediaGoblin 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 GMG_* prefix to change
|
|
the namespace to avoid collisions (or something like that).
|
|
|
|
This is a last resort; consult with the rest of the dev group
|
|
before taking this radical step.
|
|
|
|
:Q: What about submodules?
|
|
|
|
:A: pdf.js is supplied as a submodule, and other software may use that too,
|
|
to add a new submodule:
|
|
git submodule add <git-repo-of-fun-project> extlib/fun-project
|
|
|
|
Use it just like a snapshotted extlib directory. When a new clone of mediagoblin
|
|
is made you need to run
|
|
|
|
git submodule init
|
|
git submodule update
|
|
|
|
As noted in HackingHowto
|
|
|
|
Thanks
|
|
======
|
|
|
|
This policy originally copied from Status.net. Many many thanks to them
|
|
for working out such a nice system for doing things.
|