Commit | Line | Data |
---|---|---|
22712860 WKG |
1 | ========================= |
2 | External Library README | |
3 | ========================= | |
4 | ||
5c0cd1bf AL |
5 | This directory contains two kinds of things: external dependencies |
6 | specified in package.json (which gets installed into the node_modules | |
7 | directory), and full copies of third-party code, which we call | |
8 | embedded code copies. | |
9 | ||
10 | ||
11 | External dependencies specified in package.json | |
12 | =============================================== | |
13 | ||
14 | package.json is a file that specifies external code dependencies. We | |
15 | download those using the "npm" tool. As a developer of MediaGoblin, | |
16 | install npm however is convenient for you (for example, apt-get | |
17 | install npm). | |
18 | ||
19 | If you are "merely installing" MediaGoblin (and aren't attempting to | |
20 | change its code), you should know that the MediaGoblin team's main | |
21 | release download, also known as the MediaGoblin mulltipack tarball, | |
22 | contains a copy of all the code specified via package.json. | |
23 | ||
24 | As a general rule, always specify dependencies in package.json using | |
25 | "==" to pin to a specific release that you have tested MediaGoblin | |
26 | with. The MediaGoblin team always welcomes patches that merely change | |
27 | the version of a dependency so long as you have tested that the app | |
28 | works. Doing this is a valuable and significant contribution to the | |
29 | project. | |
30 | ||
31 | Other notes about the contents of package.json: | |
32 | ||
33 | * Inconsolata is available in the npm repositories, but it does not | |
34 | include the OTF font format, and at the time of writing it appears | |
35 | that PIL needs OTF/TTF and cannot accept a WOFF font file. For this | |
36 | reason, we have avoided using the Inconsolata package from npm. | |
37 | ||
38 | * Lato is available in NPM as connect-fonts-lato, but the font file | |
39 | has a different hash than the file currently in extlib, so we are | |
40 | sticking with our extlib version until someone has time to test | |
41 | the NPM version. (That could be you!) | |
42 | ||
43 | ||
44 | Embedded code copies | |
45 | ==================== | |
46 | ||
22712860 WKG |
47 | DO NOT "FIX" CODE IN THIS DIRECTORY. |
48 | ||
49 | ONLY UPSTREAM VERSIONS OF SOFTWARE GO IN THIS DIRECTORY. | |
50 | ||
51 | This directory is provided as a courtesy to our users who might be | |
52 | unable or unwilling to find and install libraries we depend on. | |
53 | ||
54 | If we "fix" software in this directory, we hamstring users who do the | |
55 | right thing and keep a single version of upstream libraries in a | |
56 | system-wide library. We introduce subtle and maddening bugs where | |
57 | our code is "accidentally" using the "wrong" library version. We may | |
58 | unwittingly interfere with other software that depends on the | |
59 | canonical release versions of those same libraries! | |
60 | ||
61 | Forking upstream software for trivial reasons makes us bad citizens in | |
0d656f44 | 62 | the Free Software community and adds unnecessary heartache for our |
22712860 WKG |
63 | users. Don't make us "that" project. |
64 | ||
65 | ||
66 | FAQ | |
67 | === | |
68 | ||
69 | :Q: What should we do when we find a bug in upstream software? | |
70 | ||
71 | :A: First and foremost, REPORT THE BUG, and if possible send in a patch. | |
72 | ||
73 | Watch for a release of the upstream software and integrate with it | |
74 | when it's released. | |
75 | ||
76 | In the meantime, work around the bug, if at all possible. Usually, | |
77 | it's quite possible, if slightly harder or less efficient. | |
78 | ||
79 | :Q: What if the bug can't be worked around? | |
80 | ||
81 | :A: If the upstream developers have accepted a bug patch, it's | |
82 | undesirable but acceptable to apply that patch to the library in | |
83 | the ``extlib/`` dir. Ideally, use a release version for upstream or a | |
84 | version control system snapshot. | |
85 | ||
86 | Note that this is a last resort. | |
87 | ||
88 | :Q: What if upstream is unresponsive or won't accept a patch? | |
89 | ||
90 | :A: Try again. | |
91 | ||
92 | :Q: I tried again, and upstream is still unresponsive and nobody's | |
93 | checked on my patch. Now what? | |
94 | ||
95 | :A: If the upstream project is moribund and there's a way to adopt it, | |
8a20ee34 | 96 | propose having the MediaGoblin dev team adopt the project. Or, adopt |
22712860 WKG |
97 | it yourself. |
98 | ||
99 | :Q: What if there's no upstream authority and it can't be adopted? | |
100 | ||
101 | :A: Then we fork it. Make a new name and a new version. Include it in | |
102 | ``lib/`` instead of ``extlib/``, and use the GMG_* prefix to change | |
103 | the namespace to avoid collisions (or something like that). | |
104 | ||
105 | This is a last resort; consult with the rest of the dev group | |
106 | before taking this radical step. | |
107 | ||
3cadb4a6 AL |
108 | :Q: What about submodules? |
109 | ||
110 | :A: pdf.js is supplied as a submodule, and other software may use that too, | |
111 | to add a new submodule: | |
112 | git submodule add <git-repo-of-fun-project> extlib/fun-project | |
113 | ||
114 | Use it just like a snapshotted extlib directory. When a new clone of mediagoblin | |
115 | is made you need to run | |
116 | ||
117 | git submodule init | |
118 | git submodule update | |
119 | ||
120 | As noted in HackingHowto | |
22712860 WKG |
121 | |
122 | Thanks | |
123 | ====== | |
124 | ||
125 | This policy originally copied from Status.net. Many many thanks to them | |
126 | for working out such a nice system for doing things. |