Publishing Logic

Updates to the documentation are published automatically when changes are made to the release branch or a version branch, which is a branch named with the {major}.{minor} level version number without the initial 'v' (e.g.: 2.5 or 3.0). Publication from a version branch will only happen if the version major.minor has already been published on the release branch. Changes can come from merging a pull request or from a push to the branch. Note that a version branch only retains the latest documentation for the version, as is also the case for the major.minor version paths on the website. As new changes to the documentation are issued, the previous information is overwritten such that only the most recent changes appear for a particular major.minor version. For example, updating a document from v2.5 to v2.5.1 will save the updated information to the 2.5 path on the website. Versions on the website are only selectable at the major.minor level.

The version number is provided in the conf.py file in the branch being processed. The cumulative list of published versions and stable version is provided from a persistent information file maintained by the publish.py script. The version number from conf.py is validated to ensure that it follows the format v{major}.{minor}[.{micro}] where {major}, {minor} and {micro} are integers containing only digits. The .{micro} portion is optional and is removed when determining which version path of the documentation to update.

Additional alpha, beta or release candidate designations can be included in the version number (e.g.: 2.6b2 or 3.0rc1); although these would likely only be pushed to the release branch. The highest non-pre-release version will be considered the stable version. Because information pushed to the release branch will always be published as latest, the automated processing assumes that any versions pushed to the release branch will always be greater than or equal to the current version in the release branch.

---

Logic Flow Steps

The logic used by the publish.py script is:

1. Is this the release branch?

   • Yes: Publish as latest and go to Step 2.
   • No: Go to Step 7.

2. Is the version number valid?

   • Yes: Go to Step 3.
   • No: Quit.

3. Is the major.minor portion of the version number in the versions list?

   • Yes: Go to Step 4.
   • No: Add major.minor portion of the version number to versions list and go to Step 4.

4. Publish as major.minor portion of the version number and go to Step 5.

5. Is the version number a pre-release version?

   • Yes: Go to Step 10.
   • No: Go to Step 6.

6. Is the major.minor portion of the version number greater than the stable version?

   • Yes: Change the stable version to the major.minor portion of the version number and go to Step 10.
   • No: Go to Step 10.

7. Is the version number valid?

   • Yes: Go to Step 8.
   • No: Quit.

8. Is the branch name the same as the major.minor portion of the version number without the leading 'v'?

   • Yes: Go to Step 9.
   • No: Quit.

9. Is the major.minor portion of the version number in the versions list?

   • Yes: Publish as major.minor portion of the version number and quit.
   • No: Quit.

10. Update the persistent information file, index.html, 404.html and JavaScript support file, and quit.

---

Example

For example, assume that our starting point is stable and latest are 2.5, version list is ['2.3', '2.4', '2.5'], and the latest published version is v2.5.1.

You want to start gathering documentation changes for an upcoming release that has not yet been issued, so you push v2.6rc1 documentation to a next_version branch created from the current master branch. The following will result:

• v2.6rc1 will not be published on the website and the v2.6 path will not be created
• version list will remain as ['2.3', '2.4', '2.5']
• stable will remain at 2.5 and show as v2.5.1
• latest will remain at 2.5 and show as v2.5.1

Note that you can alternately use a temporary 2.6rc1 branch (a prerelease branch) instead of the next_version branch. The difference would be that all pushes to this temporary branch would trigger a full build of the documentation in all languages rather than just a build in the default English base language. See the Repository Structure wiki page for more information about prerelease branches.

Later on, you issue v2.6rc1 of the software, and merge the next_version branch containing the v2.6rc1 documentation back into the master branch. Following reviews, the master branch is merged into the release branch, which results in the following:

• A new 2.6 path will be created on the website
• v2.6rc1 will be published to the latest and 2.6 paths on the website
• version list will be updated to ['2.3', '2.4', '2.5', '2.6']
• stable will remain at 2.5 and show as v2.5.1
• latest will be updated to 2.6 and show as v2.6rc1

Note that you should create a new 2.5 branch from the master branch at the point just prior to merging the next_version branch into the master branch. This will allow future changes / corrections to be made to the latest v2.5.x documentation without impacting the newly published 2.6 documentation path. Once merged, the next_version branch can be deleted, and a new next_version branch created from the master branch later when preparing documentation for the next major.minor release.

You then decide that you need to push a correction for the version v2.5.1 documentation to the 2.5 branch, which triggers the following:

• v2.5.1 will be published to the 2.5 path on the website.
• version list will remain as ['2.3', '2.4', '2.5', '2.6']
• stable will remain at 2.5 and show as v2.5.1
• latest will remain at 2.6 and show as v2.6.rc1

Later on, you release v2.6 of the software and push v2.6 documentation updates (even if it's just to remove the 'rc1' from the version number) to the master branch. Following reviews, the master branch is merged into the release branch, resulting in the following:

• v2.6 will be published to the latest and 2.6 paths on the website.
• version list will remain as ['2.3', '2.4', '2.5', '2.6']
• stable will be updated to 2.6 and show as v2.6
• latest will remain at 2.6 and show as v2.6

Note that further changes to the v2.6 documentation, including maintenance releases such as v2.6.1, should be pushed to the master branch as long as v2.6.x is the latest version of the documentation.

Subsequently, you release v2.6.1 of the software and push v2.6.1 documentation updates (even if it's just to update the version number) to the master branch. Following reviews, the master branch is merged into the release branch, which results in the following:

• v2.6.1 will be published to the latest and 2.6 paths on the website.
• version list will remain as ['2.3', '2.4', '2.5', '2.6']
• stable will remain at 2.6 and show as v2.6.1
• latest will remain at 2.6 and show as v2.6.1

You then push another change (such as a language translation correction) for the version v2.5.1 documentation to the 2.5 branch, which triggers the following:

• v2.5.1 will be published to the 2.5 path on the website.
• version list will remain as ['2.3', '2.4', '2.5', '2.6']
• stable will remain at 2.6 and show as v2.6.1
• latest will remain at 2.6 and show as v2.6.1

---