1Releasing Bareos 2================ 3 4This chapter describes how to release a new version of Bareos. 5The documentation is limited to the changes that need to be done to the sources and the git repository. 6Building and distributing source and binary packages is not the scope of this chapter. 7 8.. note:: 9 10 Consider this a step-by-step manual. The sections are meant to be carried out in that order. 11 12Deciding for a version number 13----------------------------- 14When you release you will usually need at least two version numbers: the version you're going to release and the version that will follow after that version. 15For details on the numbering-scheme, take a look at :ref:`section-version-numbers`. 16 17Usually, you will have an existing work-in-progress tag that generates pre-release version numbers for your branch. 18So the version you're going to release is probably the final version for that pre-release. 19 20Preparing the release notes 21--------------------------- 22In :sinceVersion:`20.0.0: CHANGELOG.md` release notes will be kept in :file:`CHANGELOG.md`. 23The "Unreleased" section in that file will automatically become the release notes and a new "Unreleased" section will be added afterwards. 24 25How does it work in detail? 26~~~~~~~~~~~~~~~~~~~~~~~~~~~ 27When you run :file:`devtools/prepare-release.sh` the "Unreleased" section will be renamed to the current release by :file:`devtools/new-changelog-release.sh`. 28All links to pull requests, issues, etc. will be automatically updated by :file:`devtools/update-changelog-links.sh`. 29After the release has been made :file:`devtools/new-changelog-release.sh` will be called again to add the new "Unreleased" section that will be added to the commit for the work-in-progress tag. 30 31Update version-dependent files 32------------------------------ 33There are version-dependent files in the Bareos sources that might need your attention. 34 35version.map.in 36~~~~~~~~~~~~~~ 37The file is in either :file:`core/src/cats/ddl` or :file:`src/cats/ddl`. 38Whenever the database schema version changes this file must be updated. 39Usually the developer who did a schema change should have done this. 40However, please double-check and add or update the version mapping if needed. 41 42Prepare the git commits and tags 43-------------------------------- 44There is a helper script :file:`devtools/prepare-release.sh` that will help with the process. 45You can just call the script and it will handle the version-dependent things that need to happen for the release. 46The script will also prepare all git commits that are required to release the new version and set the correct git tags. 47 48.. important:: 49 50 All changes are only done to you local git repository. For pushing these changes see :ref:`DeveloperGuide/ReleasingBareos:Publishing the release`. 51 52 53Special considerations for major versions 54~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 55Whenever you release a new major version you will be releasing more or less the master branch. 56To allow the splitting of the development (i.e. continue working on master, but allowing to work on the newly released version, too) you will have to carry out a few additional steps. 57 58.. important:: 59 Do not release from the master branch. 60 61Before running :file:`devtools/prepare-release.sh` you should create the new release-branch and switch to it using ``git checkout -b bareos-X.Y``. 62When you now run :file:`prepare-release.sh` it will only generate a new WIP-tag for your branch and nothing for the master branch. 63Also the release of the major version itself will not be visible on the master branch. 64 65To make the release visible on the master branch, you can just forward the branch pointer to the parent of the new WIP-tag. 66You can do so using ``git checkout master`` followed by ``git reset --soft <wip-tag>~`` (notice the ~). 67 68In :sinceVersion:`20.0.0: CHANGELOG.md` release notes are only per major-release. 69All sections referencing a previous release should be removed from :file:`CHANGELOG.md` before continuing work on the master branch. 70 71In :file:`docs/manuals/source/conf.py` on the master branch the setting for ``scv_root_ref`` and ``scv_banner_main_ref`` should point to the latest (i.e. your newly created) release-branch, so users will see the latest released documentation by default. 72You may also need to change ``scv_whitelist_branches`` so the release-branch will be picked up when building the documentation. 73 74The commit that contains the above changes should then be tagged as the new WIP-tag on the master branch. 75For example ``git add CHANGELOG.md docs/manuals/source/conf.py`` followed by ``git commit -m 'Start development of X.Y.Z'``. 76That commit can now be tagged with a new WIP-tag using ``git tag WIP/X.Y.Z-pre``. 77 78 79Publishing the release 80---------------------- 81To actually publish the release you push the commits and tags created earlier to GitHub. 82After you have reviewed the commits and tags that have been set in the previous release and made sure all branch pointers point to the right places (please double- and triple-check this) and you're on the correct branch, you can push the changes to GitHub. 83 84**For the release branch:** First push the branch ``git push <remote>``, then push the release-tag ``git push <remote> <release-tag>`` and if applicable push the WIP-tag ``git push <remote> <WIP-tag>``. 85 86**For the master:** If this is a new major release you also need to push master and the new WIP-tag for master. 87 88Updating GitHub Release 89----------------------- 90Pushing a tag to GitHub will implicitly create a release on the `project's list of releases <https://github.com/bareos/bareos/releases/>`_. 91The release information there is incomplete and should be updated. 92 93Go to the list described above, select your release-tag and press "Edit tag". 94In the form enter "Release X.Y.Z" for "Release title" and add the URL of the release notes to "Describe this release". 95If you're releasing a pre-release (anything with a tilde in the version number) check the "This is a pre-release" box. 96Apply the changes by pressing "Save". 97