-
-
Notifications
You must be signed in to change notification settings - Fork 13
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
.
-
Optionally, create a new branch from the
master
branch, with the new branch name as themajor.minor
of the current release. In our example, this would be2.4
. This will allow later updates specific to thev2.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 appropriatemajor.minor
version number branch. -
Update the version number of the
version
variable in theconf.py
file. In our example this would mean settingversion
to'v2.5rc1'
. Pushing these updates to themaster
branch and subsequently merging themaster
branch into therelease
branch will automatically create av2.5
path on the website, and create the appropriate links from prior versions. In addition, the system will automatically update thelatest
(default) information on the site with the new version number. Because our new version is a pre-release version, thestable
website path is not updated and will remain pointing to thev2.4
path. In addition, you can optionally create a newv{major}.{minor}
tag (i.e.:v2.5
) on themaster
branch at the point that the new version of the documentation was published. -
When publishing a maintenance or "patch" version of the current
major.minor
version, such asv2.5.1
, theversion
variable in theconf.py
file would be updated -- in this case to'v2.5.1'
. When the changes are pushed to themaster
branch and subsequently merging themaster
branch into therelease
branch, the latest (default) information would be updated automatically as well as the information in thev2.5
path on the website. The version number displayed will be that of the maintenance version, in our examplev2.5.1
; however, only themajor.minor
version will be shown in the selection list. The documentation from a previous version of thatmajor.minor
will be overwritten by the latestmajor.minor[.micro]
documentation, meaning that once thev2.5.2
documentation has been published you would not be able to go back and look at the documentation for thev2.5.1
version. Thev2.5
path on the website would only serve the latest version of the documentation for that family of versions (i.e.:v2.5.2
).
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.
The MusicBrainz Picard Documentation Project and the Picard User Guide are licensed under CC0 1.0.