This document is meant to explain the workflow to effectively and bug-freely release a new version of QGIS documentation
Different versions of documentation are usually released by the QGIS project and are somehow tied to the development cycle of the software:
- testing: targets functionalities available in the development cycle
or in versions newer than the latest Long Term Release (LTR).
Source files are available in the
master
branch. The released documentation is accessible at https://docs.qgis.org/testing. - latest: targets functionalities available in the current Long Term Release.
Documentation source files are available in
release_x.y
branch where x.y represents the version number. The released documentation is accessible at https://docs.qgis.org/latest or https://docs.qgis.org/x.y. - When the first release of the next-to-be LTR is published, a new
release_x.y
branch is also created in the documentation repository and covers features available in that version (some are not in the current LTR). The documentation is accessible through https://docs.qgis.org/x.y. When that version becomes LTR months later,latest
URL is redirected to that version.
New releases are branched off the master
branch.
Following changes are required:
This usually happens from the October release.
Instructions when the next LTR is first released and there is no LTR switch
Following changes have to be done in master
branch before you create the new release branch.
Otherwise, you will have to do the changes twice: in master and in the new branch.
- In substitutions.txt file, replace |CURRENT| value with the new version number
- In docs_conf.yml file: add the new release number to the
version_list
parameter
- In substitutions.txt file:
- Remove intermediate versions substitutions and their occurrences in the rst files
- Add substitutions for the versions of the next LTR cycle that starts (e.g. if you just create the release_3.22 branch, you should add to the master branch substitutions for 3.24, 3.26 and 3.28)
- In auto-label.yml file: update list of versions labels to listen to
- In docs_conf.yml file, add the new release number to the
version_list
parameter
- Ensure that changes to do in master before creating the new release branch are applied
- In conf.py file:
- set the
version
value (in the form x.y) - set the html_context
isTesting
option toFalse
- set the
- In README.MD file, update the badges to point to the current branch instead of master
- In Makefile file, set the
VERSION
number as in the conf.py file - In docker-world.sh file: replace
QGIS-Documentation
withQGIS-Documentation-x.y
- In cronjob.sh file:
- replace
QGIS-Documentation
withQGIS-Documentation-x.y
- replace
qgis_docs_master_build
withqgis_docs_x.y_build
- replace
- In doctest.dockerfile: set the project container to pull QGIS sources from (i.e.
release-x_y
) - In main index.rst file: replace
testing
withx.y
in the Table Of Contents
-
⚠️ Make sure that the C++ API documentation of the new version is available, or at least add it to the index page. -
⚠️ Make sure that the PyQGIS documentation of the new version is available.- Update build-docker.yml with the latest release
- Update pyqgis_conf.yml with the latest version
- Add the new docs to the index page
- Add new labels to triage issues and pull requests:
backport <new_branch>
, new target versions - Create a new milestone for the new cycle of LTR that starts
- Update commands to publish the new version (in English, as html, zip and pdf) and avoid redirecting it to testing
In February, the new version is labeled as LTR, and replaces the previous one in many places.
Instructions when the new LTR officially takes place
- In docs_conf.yml file: add target languages to the
supported_languages
parameter. These are the languages that will be published in the documentation. A threshold of 5% is currently applied to candidates. - In docker-world.sh file: complete the
langs
variable with the supported languages - In the makefile: add the supported languages to the
LANGUAGES
parameter - Copy the locale folder from the old LTR branch to the new LTR branch
- Generate new English source files (see instructions in README file)
-
⚠️ Make sure that the translated files from the old LTR branch have been correctly pasted to the new LTR branch - Link the new LTR branch to the QGIS-Documentation project (read docs on Transifex)
- If the connection above does not correctly proceed and update files in the transifex platform, see workaround instructions in README file
- In fix_versions.sh file:
- add the old LTR number to the
DEPRECATED
parameter - add the new LTR number to the
DOCVERSIONS
parameter
- add the old LTR number to the
- In pofiles.yml: update branch to the new LTR branch in order to generate updated English *.po source files to push to Transifex
- In pull_minimize_translations.yml: update target_branch to the new LTR branch in which to pull translations from Transifex
- In translation_statistics.yml: update target_branch to the branch(es) in which to generate translation statistics
- Redirect
latest
URL to the new LTR pages - Update commands to publish the new version (in released languages, as html, zip and pdf)
Many parts of the process are currently manual. This sometimes results in failing builds because some steps were overlooked/forgotten. Automating the process as much as possible would lower the risk and make it less time consuming.
-
Some values are somehow copy-pasted across places while they could likely be put in a variable:
- languages list: they are defined in docs_conf.yml, makefile, docker-world.sh
- version number: it is defined in conf.py, makefile, docker-world.sh, cronjob.sh, doctest.dockerfile