The Fedora Documentation Project maintains the XML source for most Fedora documentation in git repositories on fedorahosted.org. Generally, each repo contains a "master" branch that contains a working copy of the document, and a set of stable branches for various Fedora releases. The version of the XML in these stable branches forms the basis for translations by the Fedora Localization Project. We do not generally make incremental changes to the XML in stable branches because to do so would break translations. Instead, we make corrections and improvements to the document in the "master" branch.
Nevertheless, we sometimes need to change the XML in a stable branch:
- between the time we branch a document for translation (usually during the Alpha phase of a release) and the GA release. Details can change between Alpha, Beta, and GA, and we try to keep our documentation up-to-date with these changes.
- when someone finds a serious error or omission in documentation, particularly one that could lead a user to lose data, make a system inaccessible, or expose a system to a serious security risk.
In each case, you should discuss proposed changes with the Localization Team on their mailing list at trans@lists.fedoraproject.org before making those changes. You should indicate a firm timeframe for the changes, so that translators can avoid the risk of edit conflicts when you update the PO files.
Once you have obtained permission from Localization, you will need to update the XML, POT files, and PO files in the stable branch. If you suspect that the changes might take some time (more than an hour or so), consider filing a request with l10n-requests to have file submissions temporarily turned off while you update the files, then update the request when you have finished the update and ask for file submissions to be turned on again.
Preparation
In the root directory of the checked-out document (the one that contains the publican.cfg file):
0.1 Change into the master branch
- git checkout master
0.2 Make sure that your master branch is up to date:
- git pull
0.3 Make sure that you have a local copy of the stable branch that you need to change, for example:
- git branch --track f21 origin/f21
0.4 Change into the stable branch
- git checkout f21
0.5 Make sure that the stable branch is up to date:
- git pull
0.6 Make sure that your Publican installation is the latest version
- sudo yum update publican*
Updating stable content
1. Change into the master branch
- git checkout master
2. Copy the contents of the en-US directory (or at least, the XML files that need to be updated) to a temporary location on your system.
3. switch to the stable branch, for example, f21:
- git checkout f21
4. replace the relevant files in the en-US directory with the copies that you created in Step 2.
5. if there are now files in the en-US directory that are no longer used in the document, remove them:
- git rm en-US/ObsoleteChapter.xml
6. remove the pot directory:
- git rm -r pot
7. commit your changes so far:
- git add en-US
- git commit -m"Update XML"
- git push
8. generate a new pot directory:
- publican update_pot
Take note of any warnings from Publican about XML files that are not used in the book. If you see any such warnings, remove those files from the en-US directory and the corresponding files from the pot directory and language directories, using the instructions in step 5 to step 7. For example, you might have to remove en-US/ObsoleteChapter.xml, pot/ObsoleteChapter.pot, de-DE/ObsoleteChapter.po, ru-RU/ObsoleteChapter.po, and ja-JP/ObsoleteChapter.po.
9. update the PO files for each language:
- publican update_po --langs=all
10. commit your changes:
- git add .
- git commit -m"Refresh POT and PO files"
- git push
11. notify trans@lists.fedoraproject.org that the update is complete.