GPG guide/Repo Restructure
Contents
Current processes for git usage (FSF only)
Translators work in enc/master (or in their own branches on enc, merging with master when they are done). At any given time, some of the translations in enc/master are ready for publication and some are not.
Once translators notify the FSF that their language is ready, the FSF reviews the translation in enc/master by viewing it online at https://enc-dev0.fsf.org. Once we are satisfied, we manually copy the directory for the language from from enc/master to enc-live master locally, test it locally and then commit and push directly to the live site.
- The testing environment is farther from the live environment than is ideal, but the translation will already have been tested on the dev server and on your local machine, so it's really pretty unlikely that something will go wrong when it's on live. Still, this system is sloppy and produces poor git records of the publishing process.*
Zak's Proposed New System
- If you have tweaks or corrections, please make them in this section. If you'd like to propose an entirely separate new system (which you are more than welcome to do), please start a new section below.*
The current method is problematic because all the translators are working on the same branch (enc/master). If one language is finished and another is not, the FSF cannot publish the finished language by merging enc/master into enc-live master, because that would also publish the unfinished language. Instead, the FSF manually copies a finished language's directory from a local checkout of enc/master to a local checkout of enc-live/master, which is not the best practice because it forgoes testing in an environment matching the one where the translation will be displayed in enc-live.
This is a proposal for a new system (as well as a transition plan from the old system).
Branch structure
Email Self-Defense has two repositories, which I'll refer to here as enc (for development and testing) and enc-live (the contents of which are served directly to the live site). enc has many branches, but enc-live has only one:
- enc/master** - Translators should never push anything here unless directed by the FSF. Only for final testing during the FSF's publishing process. Hosted at https://enc-dev0.fsf.org/master.
- enc/next-version** - holding pen for new versions while they are being developed in English. Hosted at https://enc-dev0.fsf.org/next-version.
- enc/LANGUAGECODE-translation** - one such branch for each language. This is where first-time translations and translation updates are developed.
- live/master** - the only branch in the live repo, it is hosted at https://emailselfdefense.fsf.org. This is edited only be the FSF, and only by merging from origin/master.
Translating
When developing a new translation or working on any update or change to an existing translation, translators should work in the corresponding branch for their translation (origin/LANGUAGECODE-translation). If it doesn't exist, please create it from the master branch.
When your translation is complete and peer reviewed, send an email to campaigns@fsf.org (FIXME COPY THIS PART). The FSF will review your branch, merge it into master, test it by reviewing that everything displays correctly on https://enc-dev0.fsf.org/next-version, and then publish by pushing enc/master to enc-live/master.
Reviewing your work during translation
Previously, the recommended way to review your work was to push to enc/master and view it on the Web at https://enc-dev0.fsf.org. However, with the new system, we aren't allowing partially finished work on enc/master. From now on, you should set up your own development server on your computer and use it to review your work. (FIXME LINK TO SOME RESOURCES FOR THIS) If you have trouble setting up your development environment, please reach out for help to the esd-translators list. Do not push to master!
Developing a new version (FSF only, English only)
Copy the current contents of enc/master into enc/next-version and edit it. A normal merge most likely won't work -- you'll have to actually copy or use another git technique.
When it's ready, merge enc/next-version into enc/master and then delete everything in enc/next-version and replace it with a single page that explains there is no new version in development at the moment.
Transition plan
Translators should remove any branches on the FSF's server that they are not actually using. The FSF removes the confusing and outdated origin/live branch (which is not actually live anywhere).
There is currently some unfinished translation work in enc/master. Translators: **please make a new translation branch called from master and work from there.** In one month, Zak will create a backup snapshot of enc/master and then will **overwrite master with a current copy of live**.
