Project Workflow

The typical (simplified) steps for making a change to the documentation is:

1. Change proposed
2. Proposed change reviewed
3. Change approved and applied
4. Updated documentation translated
5. Documentation translations published

Following, each of these typical steps is described in greater detail.

1. Change proposed

Source branch: various (specific to the change / pull request)
Target branch: master (or major.minor for changes to prior versions of the documentation)

Proposed changes are made to the English base language documentation source files in a branch created from the current master branch. A pull request is created by the content contributor to merge the changes into the master branch. If the change is to an earlier major.minor version of the documentation, the working branch will be created from the associated major.minor branch and the changes will be merged into the major.minor branch rather than the master branch.

2. Proposed change reviewed

Source branch: various (specific to the change / pull request)
Target branch: master (or major.minor for changes to prior versions of the documentation)

The pull request with the proposed changes is reviewed by the editor for overall quality and consistency with the document structure and presentation, including restructured text encoding. The pull request is also reviewed to ensure that any technical content is correct. Any review comments applied should be addressed by the content contributor, making changes if required or explaining why the proposed content should not be changed.

3. Change approved and applied

Source branch: various (specific to the change / pull request)
Target branch: master (or major.minor for changes to prior versions of the documentation)

Once the pull request has received editorial and (if necessary) technical approval and all review comments have been addressed, it is merged into the master branch (or major.minor branch for changes to prior versions of the documentation). In preparation for translation of the changes to other languages, the editor will generate updated translation template *.pot files which are are uploaded to the Weblate translation server used for the project. The translation leads are notified that there are changes that require translation. The changes can be published at this time (without all translations complete) by merging the master branch into the release branch.

4. Updated documentation translated

Source branch: master (through Weblate)
Target branch: master

The translation leads arrange to have the translations updated to accommodate the changes to the documentation. Depending on the tools used for translating and producing the *.po files, the translators may submit pull requests directly or the translation lead may submit the updates from a translation site. The pull requests will be reviewed by the translation lead for the language to ensure translation accuracy. Once approved by the translation lead, the pull request will be merged. If the translation updates are being managed on the Weblate server, then they will be merged automatically into the master branch.

5. Documentation published

Source branch: master
Target branch: release (or major.minor for changes to prior versions of the documentation)

Once the translations are complete and merged into the master branch, the translation lead will initiate a pull request to publish the updated documentation for their language. The pull request will be reviewed by the editor to ensure proper restructured text encoding. Once approved by the editor, the pull request will be merged and published.

---

Notes

Pushing / merging to the release branch will automatically trigger building the updated documentation files and update the gh-pages branch from which the files are served. This ensures that the latest approved changes are published promptly, although it also means that translations may lag behind the English base language version. Please see the Publishing Logic and Publishing a New Version wiki pages for more information.

---