How to perform a semi-automatic release

Prerequisities

• System with python3.6 or greater, installed PyGithub module.

• A GitHub token - get one on https://github.com/settings/tokens. Choose repo scope.

Process

1. Clone a clean openscap repository:

   git clone --recurse-submodules https://github.com/OpenSCAP/openscap.git

2. Create .env file

   You are supposed to define environment variables that contain sensitive information, s.a. GitHub access tokens. Create an .env file in the release_tools directory (i.e. where the release scripts are). Put your GitHub token in the .env file, so it contains the following line:

   GITHUB_TOKEN='<your token here>'

3. Check out that the information within versions.sh is accurate.

   OpenSCAP versions are supposed to have correct values from the previous build (see the step 6).

4. Run up_to_compliance_check.sh.

   In the ideal case, the script ends after the ABI compatiblity check finishes. Review the check results and act accordingly to them.

5. Run handle_ltversions.sh.

   According to the result from the compliance check (and the decision what to do about possible API/ABI changes), you run the script with an argument bugfix, backwards_compatible or breaking_change.

   Use this guideline to decide:

   • bugfix: No changes of API/ABI, the code got just some improvements under the hood.

   • backwards_compatible: API/ABI is backwards compatible - the API was expanded, new symbols were introduced.

   • breaking_change: API/ABI is not backwards compatible - the API was modified, symbols were removed, types have changed…​ If this happens, think about dropping symbols marked with openscap OSCAP_DEPRECATED() macro.

   This changes the libtool library version number so it reflects the API/ABI change.

6. Update the NEWS and make the release commit.

   Make sure that everything in the repository is in place, and that the only thing missing is the NEWS file and tags. Use the news_template.sh script to generate a starting point for your NEWS file. Update the AUTHORS file for missing authors and the naming.sh file if there are duplicate author entries.

   Use it to update the NEWS file and commit it.

   The last commit before the release has to have the openscap-<version> message (e.g. openscap-1.3.2).

7. Create tarballs and GitHub release.

   In a clean copy of the release branch run cmake .. && make package_source in the build directory.

   Create new GitHub release with the name of the vesrion (e.g. 1.3.2) being released.

   Add relevant part of the NEWS file as a release description.

   Attach openscap-X.Y.Z.tar.gz and openscap-X.Y.Z.tag.gz.sha512 files to the GH release, created against the release tag.

8. Run new-release.sh.

   This will create and push version tags, create new GitHub release and handle milestones swap. Finally, it will bump version numbers in versions.sh to be ready for the next (e.g. 1.3.3) upstream release.

9. Build OpenSCAP for Windows

   The Windows build process is described in Developer Manual.

   The Windows Installer can be built by running cpack in the build directory. CPack will produce 2 files:

   • OpenSCAP-${version}-win32.msi which is the installer package

   • OpenSCAP-${version}-win32.msi.sha512 that contains SHA512 checksum of the installer

   Upload both of the files to the GitHub release.

To be done

• Full GitHub integration: Blocked by PyGithub/PyGithub#525

• Full Jenkins integration.