Members-Serverguide

Differences between revisions 33 and 34
Revision 33 as of 2013-08-10 22:53:23
Size: 10942
Editor: dsmythies
Comment: add link to build page
Revision 34 as of 2013-08-15 03:31:08
Size: 10968
Editor: dsmythies
Comment: fix multiple bugs on one commit example
Deletions are marked like this. Additions are marked like this.
Line 62: Line 62:
bzr commit --fixes lp:123456 --fixes lp:123457 -m 'some notes; by John Smith' bzr commit --fixes lp:123456 --fixes lp:123457 -m 'some notes; LP: #123456; LP: #123457; by John Smith'

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 (#100000 here) has been reviewed and approved, it needs to be integrated into the main branch:

1. Set up a local working branch:

mkdir sguide-1204
cd sguide-1204
bzr branch lp:serverguide/precise 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.

2. Always run the validate script before any changes, just in case something is wrong:

scripts/validate.sh serverguide/C/serverguide.xml

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

Notes:

  1. The 'bzr merge' command is taken from the merge proposal page on Launchpad. See 'To merge this branch:'
  2. Instead of 'bzr diff' you can do 'bzr cdiff' to get some colour (you will need package 'bzrtools' installed).
  3. 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.
  4. '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 Precise branch.

bzr commit --fixes lp:123456 -m 'Edits per MP: #100000; LP: #123456 some notes about whatever; by John Doe'
bzr push lp:serverguide/precise

Notes:

  1. If working with the development release branch then "lp:serverguide" can be used instead of "lp:serverguide/branch_name".
  2. 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; by John Smith'

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).

Publishing changes

Members of the ubuntu-core-doc team can publish their changes directly to the branches. This is the procedure:

  1. 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.

  2. 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 'typoes and programlisting fixes; LP: #1197137 LP: #1197143 LP: #1200816'
  3. Then push your commit to the common branch by running

    bzr push lp:serverguide/name_of_branch

Updating the .po files

This is how to update a release's .po files (historically, for the dev release this is done a few weeks after String Freeze and before final release):

1. Create a working branch

bzr branch lp:serverguide/precise precise_po_update

2. Request from Launchpad the entire po set (change the series name as required):

https://translations.launchpad.net/serverguide/precise/+export

3. Wait for the e-mail stating that the set is ready.

4. Get 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:

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 'Updated the po files; by Doug Smythies'
bzr push lp:serverguide/precise

Updating the .pot file

Simply run the script to generate a new .pot file and push the result:

scripts/get-pot.sh

Updating help.ubuntu.com

Place holder - In progress 2013.08.10

See also: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/BuildingDocumentation

On a per 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). Check the .xml files for any needed version related changes and if automated entity substitution can be used instead.

New Series Set Up

For each release cycle, a new master branch needs to be created in Launchpad. Saucy in this example.

  1. Push the previous series into a new code branch:

mkdir new_series_sguide-1310
cd new_series_sguide-1310
bzr branch lp:serverguide/raring
cd raring
bzr push lp:~ubuntu-core-doc/serverguide/saucy
  1. From the serverguide project page select "Register a series".

  2. Fill in some fields:
    • Name: saucy

    • Summary: Work for Ubuntu 13.10, codenamed "Saucy Salamander"; release October 2013.

    • Branch: ~ubuntu-core-doc/serverguide/saucy

  3. In the project page, select "Change details" and near the bottom change Development focus to serverguide saucy.

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. (Doug: was it right to to this?)

Go to the "Configure Translations" page and change the "Translation focus" to the new series.

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:

https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/RELEASEUbuntuServerGuide

For example, the Raring page was backed up here:

https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/RaringUbuntuServerGuide

2. Set up the new page by performing some obvious replacements in its contents:

  • Top heading
  • "Current release guide"
  • "Last 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)

UTF-8 Policy

There should be no multi-byte UTF-8 characters in the master .xml source files. Obvioulsy, multi-byte UTF-8 characters are essential for the translated documents. The only multi byte UTF-8 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:

grep --color='auto' -P -n "[\x80-\xFF]" *.xml

Opening and closing quote characters can still be included via use of <quote> and </quote> tags within the .xml files.

DocumentationTeam/SystemDocumentation/Repository/Members-Serverguide (last edited 2017-12-08 22:45:26 by dsmythies)