This page offers guidance for documentation committers working with the serverguide project. It is a supplement to the main Members page.
This page is not intended for serverguide contributors, who should be using the serverguide contributors focus page instead.
Working with Merge Proposals
Once a merge proposal (in these examples #100000 by John Doe) has been reviewed and approved, it needs to be integrated into the main branch:
1. Set up a local working branch (typically, a member will always have an up to date working branch already):
mkdir sguide-1604 cd sguide-1604 bzr branch lp:serverguide/trunk mp_100000 cd mp_100000
Above, the local branch has been named mp_100000 (merge proposal #100000) for clarity purposes only. It's name is arbitrary. If an previously existing local working branch is being used, double check that it is up to date:
2. Always run the validate script before any changes, just in case something is wrong:
3. Merge the proposed branch into the local one and perform some checks:
bzr merge lp:~jdoe/serverguide/some-review scripts/validate.sh serverguide/C/serverguide.xml bzr diff | more make serverguide-html make serverguide-pdf bzr status
- The 'bzr merge' command is taken from the merge proposal page on Launchpad. See 'To merge this branch:'
- Instead of 'bzr diff' you can do 'bzr cdiff' to get some colour (you will need package 'bzrtools' installed).
- Making the HTML and PDF files allow you to view the actual results with a browser/viewer. Not always necessary if the change is small.
- 'bzr status' yields a summary of the current merge proposal.
4. Once everything is in order, which it should be for an approved merge proposal, push it to the main branch on Launchpad. Note that the below example is for merging with the trunk branch.
bzr commit --fixes lp:123456 -m 'Edits per MP: #100000; LP: #123456 some notes about whatever' --author='John Doe <email@example.com>' bzr push lp:serverguide/trunk
- If working with the main development trunk branch then "lp:serverguide" can be used instead of "lp:serverguide/trunk".
- For a longer commit message, consider using the "--file=filename" option, where "filename" contains the actual message.
- Multiple fixed bugs can be done with one commit line. Example:
bzr commit --fixes lp:123456 --fixes lp:123457 -m 'some notes; LP: #123456; LP: #123457' --author='John Doe <firstname.lastname@example.org>'
A proposed branch can also be linked to a bug report afterwards via its Launchpad web page (i.e. if forgotten during the above step).
Committing changes directly
Members of the ubuntu-core-doc team can commit their own work directly to the branches. It is expected that members will use experience and good judgement to decide if their changes should be submitted via merge proposal, for review by colleagues, or committed directly. This is the procedure:
First, update your branch to the current version by running
bzr pull lp:serverguide/name_of_branch
Note: please do not use bzr merge for updating your branch.
Then make your changes and commit them with
bzr commit -m 'Description of changes'
Note: If a bug is fixed, please include the bug number in the description in this format: LP: #bugnumber. You can also associate the branch with the bug in Launchpad by including this in your commit command: --fixes lp:bugnumber Examples:
bzr commit --fixes lp:1200992 -m 'do not include file that does not exist, main.js; LP: #1200992' bzr commit --fixes lp:1197137 --fixes lp:1197143 --fixes lp:1200816 -m 'typos and program listing fixes; LP: #1197137 LP: #1197143 LP: #1200816'
Then push your commit to the common branch by running
bzr push lp:serverguide/name_of_branch
PO and POT files
These files are related to translations and need to be managed depending on the situation.
Translatable strings are stored in a single "POT file" (serverguide/po/serverguide.pot) that is generated from the English sources. It needs to be generated/extended and uploaded to Launchpad in order to make new material accessible to the Translations team.
Translated strings for each language end up in that language's "PO file" (ex: po/fr.po). They need to be downloaded from Launchpad and integrated into the appropriate branch on Launchpad in order for translations to be available for publication.
This is the idealized workflow for all contributions to the guide:
- a cycle of English contributions (2 years minus a few months; LTS guide released every 2 years)
- that cycle finishes and the POT file is extended and uploaded
- a cycle of translation (a few months)
- that cycle finishes and the PO files are updated and uploaded
- publication on help.ubuntu.com
However, translators do not necessarily wait for their cycle to begin so it makes sense to occasionally upload an extended POT file. There should be no reason to update/upload PO files unless followed by a subsequent publication.
Extending the POT file
Within an up-to-date branch, run a script to extend the .pot file:
Then push the branch to Launchpad.
Updating the PO files
Historically, for the development release, this is done a few weeks after String Freeze and before final release.
1. Create a working branch
bzr branch lp:serverguide/trunk trunk_po_update
2. Request from Launchpad the entire po set (change the series name if required):
3. Wait for the e-mail stating that the set is ready.
4. Get the file and unpack the file set to some location.
tar xzf launchpad-export.tar.gz
5. The file names will be serverguide-LN.po (where LN is each language), but they need to be LN.po:
cd serverguide/po rename 's/(serverguide-)(.*)\.po/$2.po/' *.po
6. Check that the po files are actually newer and that the number of files is the same.
grep PO-Rev *.po | more
However, the above can give misleading results, as the file can change without PO-Revision changing. Similarly, the translations status web page can show misleading information in the "Last Changed" column. So, also check the version of .pot file this .po file is based on:
grep "POT-Cre" *.po | more
7. Replace the old .po files with the newer ones. (Do NOT copy the .pot file from the downloaded file set.)
8. Check bzr status, commit, and push the branch:
bzr status bzr commit -m 'Update the po files' bzr push lp:serverguide/trunk
9. On Launchpad, under translations, check the "Import Queue". The files will probably show a status of "needs review". If needed right away, select "serverguide" as the template and then "click" on the "approve" button, repeating for each file. If an overnight import delay can be tolerated, wait a day for automated import.
Publishing (updating help.ubuntu.com)
For a more general overview (not Server Guide specific), see BuildingDocumentation.
The static pages on help.ubuntu.com (as opposed to the community wiki) are updated automatically every 24 hours with HTML files from the help.ubuntu.com bzr branch on Launchpad. Here we show how to update the portion of that branch that will lead to the publication of the Server Guide (modification of an existing one or the creation of a new one).
Make a working directory:
export WORK_DIR=~/bzr/update-help_2014-08-28 mkdir -p $WORK_DIR
Download the current help.ubuntu.com branch:
cd $WORK_DIR bzr branch lp:help.ubuntu.com
Download the current serverguide branch and perform the builds:
- There are problems when compiling the PDF for languages other than English, so this is currently omitted in the below commands:
- This, in turn, causes "make serverguide-lang-help" to complain about the missing PDF file for each language. Ignore these errors.
For 14.04 and later (example is for when 14.04 was the still the trunk series):
cd $WORK_DIR bzr branch lp:serverguide/trunk serverguide-14.04 cd serverguide-14.04 scripts/build_all
The resulting files are under $WORK_DIR/serverguide-14.04/build/help.
Modify an existing guide
Replace the corresponding directory of the help branch with the new directory. For 14.04:
cd $WORK_DIR/help.ubuntu.com/14.04 rm -r serverguide cp -a $WORK_DIR/serverguide-14.04/build/help serverguide
Create a new guide
If a new Ubuntu LTS version has been released a new guide needs to be created. So before copying the new files over, edit the surrounding index.html files and add a directory to the branch corresponding to the new release (ex: 16.04). [TODO: need explicit files/instructions]
Push new content
Send new content to the help branch on Launchpad.
Pushing new content to the help branch is the last step before it becoming visible to the public. Test thoroughly before doing so.
cd $WORK_DIR/help.ubuntu.com bzr commit -m 'Update serverguide 14.04' bzr push lp:help.ubuntu.com
In 24 hours verify that help.ubuntu.com has been properly updated. Set any related bug reports to "Fix Released" status.
Series Related General Edits
On a per LTS release cycle basis, there are a few simple changes required. While they could be done by a documentation contributor via a merge proposal, they tend to fall to documentation committers. Update the various forms of distro information in libs/global.ent. Update the version in libs/ubuntu.xsl for the help link (Entity substitution can not used for libs/ubuntu.xsl). The year for the copyright notice might need to be incremented, libs/legalnotice.xml. Check the .xml files for any needed version related changes and if automated entity substitution can be used instead.
New Series Set Up
Note: We have changed to a master "trunk" series that will always be the focus series.
At some point in every LTS release cycle there will come a time when edits specific to the new release, and not backwards compatible with the current LTS release, will be required, typically several months before the release date. A new series needs to be left behind on Launchpad, and the trunk series becomes the next LTS release master branch.
- Push the trunk series into a new code branch:
mkdir new_series_sguide-1404 cd new_series_sguide-1404 bzr branch lp:serverguide/trunk cd trunk bzr push lp:~ubuntu-core-doc/serverguide/trusty
From the serverguide project page select "Register a series".
- Fill in some fields:
Summary: Work for Ubuntu 14.04, codenamed "Trusty Thar"; released April 2014.
New Series Translations Set Up
Note: In progress for raring. These notes subject to change and/or completion.
Make sure the .pot file is current. Pick up the latest .po files, as the starting point, otherwise there might be a great may import errors like this (as happened on raring):
Imported, but with errors: 1597. "This message was updated by someone else after you got the translation file. This translation is now stored as a suggestion, if you want to set it as the used one, go to https://translations.launchpad.net/serverguide/raring/+pots/serverguide/fr/+translate and approve it.":
After a new serverguide series has been set up, open the "Translations Tab" or go to https://translations.launchpad.net/serverguide and on that page, under the "All translatable series" area, there should be a "Set up translations for a series" area with the new series listed. If not, then someone else may have already initialized the tranlations for the series, in which case it should appear in the "All translatable series" list and the "Set up ..." section will not even appear.
Manual input is preferred (input from Matthew East).
This does not need to be done until immediately after the documentation string freeze, when it must be done. It is really a matter of balancing how much the strings are likely to change against giving translators as much time as possible to do their work. In favour of opening translations early, it gives translators more time; but if strings then are changed by the doc-committers in the interim, then translators' work can be wasted. It is fine to open the translations at string freeze, but in a particularly good release when a lot of doc work has been done early in the release, then they could be opened earlier. The reality is usually that both documentors and translators are given so little time at the end of a release to work that things get squeezed.
Go to "Change Synchornization Settings" and "Import Settings" and set it to "Import template and translation files". Save settings. Also request a one-time import.
Go to the "Configure Translations" page and verify that the "Translation focus" is set to "serverguide trunk" (which it should always be).
Check the "Import Queue", but be aware that it might take some time for the files to appear in the queue. The files will probably show a status of "needs review". If needed right away, select "serverguide" as the template and then "click" on the "approve" button, repeating for each file. If an overnight import delay can be tolerated, wait a day for automated import.
It might take awhile (maybe several hours), but the translations status pages should become visible with status. Check that the new strings appear as untranslated, they might be hard to find.
New Series Serverguide Contributors Focus Wiki
On a per release cycle basis, the Serverguide contributors focus wiki needs to be set up:
1. Back up the current page by copying it to:
For example, the Raring page was backed up here:
2. Set up the new page by performing some obvious replacements in its contents:
- Top heading
- "Current release guide"
- "Previous release version of this document"
3. Reset the contribution table by blanking any edited cells.
4. Review the priorities in green (i.e. do not put as priority something that was reviewed during the last release unless for a good reason, like rapidly changing technology)
Obsolete Old Series Cleanup
When an LTS series goes past EOL (end of life), some cleanup is desirable:
1. For the series "Overview", under https://launchpad.net/serverguide/series_name, set the "Status" to Obsolete.
2. For the series "Code", under https://code.launchpad.net/~ubuntu-core-doc/serverguide/series_name, set the "Status" to Abandoned.
3. For the series translations, under https://translations.launchpad.net/serverguide/series_name/+pots/serverguide/+edit, uncheck the "Template is active" box, then select the "Change" button.
4. Only when absolutely certain, for the "Overview", under https://launchpad.net/serverguide/series_name, select "Delete series", which should now have no impediments for doing so. There will probably be a list of items that will become untargeted as a result, but that is O.K. because we don't care anymore.
There should be no multi-byte or non ACSII characters in the master .xml source files. Obviously, multi-byte UTF-8 characters are essential for the translated documents. The only multi byte UTF-8, non ASCII, characters in the master source files are two in ubuntu.xsl defining the double >> character used in the HTML link trails, and such is consistent with other Ubuntu docs. To check for garbage bytes:
LANG=C grep -P -H -n "[\x80-\xFF]" *.xml or scripts/ascii_checker.py --only-matching --encoding ascii serverguide/C/*.xml
Opening and closing quote characters can still be included via use of <quote> and </quote> tags within the .xml files.