Publishing a New Version

Versions are available as major.minor only and do not include the micro component of the version number that is added for maintenance or "patch" versions. The micro portion of the version number is still included in the conf.py file, and will be displayed in the document provided. For example the documentation identified as 2.5 in the version selection list would serve the latest maintenance release such as v2.5.2. As patches are released, if the documentation needs to be changed the main major.minor version of the documentation will be updated, and not create new documents for each maintenance release. In general, this will happen automatically simply by pushing the changes to the master branch, and after reviews merging the master branch into the release branch.

When a new major.minor version of Picard is released (including pre-release versions -- alpha, beta or release candidate) along with the associated documentation, the following steps should be followed. For this example, the current version is v2.4.4 and we are now releasing version v2.5rc1.

1. Optionally, create a new branch from the master branch, with the new branch name as the major.minor of the current release. In our example, this would be 2.4. This will allow later updates specific to the v2.4 family of releases, such as corrections or language translations. It is unlikely that the documentation for prior releases will need to be updated, but this ensures that such updates can be applied if required, simply be pushing the changes to the appropriate major.minor version number branch.

2. Update the version number of the version variable in the conf.py file. In our example this would mean setting version to 'v2.5rc1'. Pushing these updates to the master branch and subsequently merging the master branch into the release branch will automatically create a v2.5 path on the website, and create the appropriate links from prior versions. In addition, the system will automatically update the latest (default) information on the site with the new version number. Because our new version is a pre-release version, the stable website path is not updated and will remain pointing to the v2.4 path. In addition, you can optionally create a new v{major}.{minor} tag (i.e.: v2.5) on the master branch at the point that the new version of the documentation was published.

3. When publishing a maintenance or "patch" version of the current major.minor version, such as v2.5.1, the version variable in the conf.py file would be updated -- in this case to 'v2.5.1'. When the changes are pushed to the master branch and subsequently merging the master branch into the release branch, the latest (default) information would be updated automatically as well as the information in the v2.5 path on the website. The version number displayed will be that of the maintenance version, in our example v2.5.1; however, only the major.minor version will be shown in the selection list. The documentation from a previous version of that major.minor will be overwritten by the latest major.minor[.micro] documentation, meaning that once the v2.5.2 documentation has been published you would not be able to go back and look at the documentation for the v2.5.1 version. The v2.5 path on the website would only serve the latest version of the documentation for that family of versions (i.e.: v2.5.2).

---

Notes

The system currently relies on subsequent changes to the master branch to have the same or higher version number. Submitting changes with an earlier version number will update the appropriate release branch, but will also place the lower version number in the latest (default) information.

The system does not currently rely on tags attached to a commit to identify and serve the requested version information. Although tags are not required, it may be useful to tag the master branch with v{major}.{minor} (e.g.: v2.6) at the point where a new major.minor version of the documentation is created.

Please see the Repository Structure and Publishing Logic wiki pages for more details on the repository structure and the automated publishing process.

---