-
-
Notifications
You must be signed in to change notification settings - Fork 13
Project Workflow
The typical (simplified) steps for making a change to the documentation is:
- Change proposed
- Proposed change reviewed
- Change approved and applied
- Updated documentation translated
- Documentation translations published
Following, each of these typical steps is described in greater detail.
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.
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.
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.
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.
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.
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.
The MusicBrainz Picard Documentation Project and the Picard User Guide are licensed under CC0 1.0.