Skip to content

Latest commit

 

History

History
 
 

release_tools

README.adoc

How to perform a semi-automatic release

Prerequisities

Process

When releasing alpha/pre-releases, please keep in mind how RPM handles the versioning. Please see how is this handled in SPEC file https://fedoraproject.org/wiki/Packaging:Versioning before you build Fedora and RHEL packages.

  1. Ensure the project is in a good shape for the release

  2. Clone a clean openscap repository:

    git clone --recurse-submodules [email protected]:OpenSCAP/openscap.git

  3. 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>'

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

    This file contains some variables that differ among the releases:

    • version

    • previous_version

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

  5. Run up_to_compliance_check.sh.

    This script automatically performs the following actions:

    • Build and check build, execute CTest locally

    • Check Python bindings

    • Perform ABI compliance check

    In the ideal case, the script ends after the ABI compatiblity check finishes. Review the check results and act accordingly to them. Read the report, if there is an ABI issue (some symbols were changed / removed), fix it before proceeding further!

  6. 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. The version number is changed in the following way:

  7. Perform scratch builds.

    Run make package_source and perform a scratch build on Fedora and RHEL in order to verify that the prepared OpenSCAP upstream release will be able to be built and packaged in these Linux distributions.

    You have to be a Fedora packager in order to be able to perform Fedora scratch builds.

    make package_source
cp openscap-$version.tar.gz ~/fedora-packages/openscap/
cd ~/fedora-packages/openscap/
rpmdev-bumpspec -c "upgrade to the latest upstream release" \
-n $version openscap.spec
fedpkg build --scratch --srpm

    Use an analogous process also for RHEL.

    If something went seriously wrong with the tests (e.g. a very bad pointer handling was revealed), you may want to abort the release process and fix those problems first.

  8. 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).

    Tag the commit and push the changes to upstream. You need to be allowed to push without pull requests in the GitHub repository settings.

    git tag $version
git push origin maint-1.3

  9. 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 version 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.

  10. Run new-release.sh $new_version.

    You need to provide the expected next version, ie. if you release 1.3.7 you should put there 1.3.8. This will handle milestones swap on GitHub and it will bump version numbers in versions.sh to be ready for the next upstream release.

    Then, change the version to expected next version in /CMakeLists.txt

    Commit and push the changes.

  11. Generate and publish documentation.

    Generate documentation by running cmake -DENABLE_DOCS=ON .. && make docs. Then, upload the generated OpenSCAP User manual and Doxygen API documentation to https://static.open-scap.org/ (Ask project maintainers for information on how to update https://static.open-scap.org/).

  12. Build packages for RHEL and Fedora.

  13. Send announcement.

    Check out https://www.redhat.com/archives/open-scap-list/2017-August/msg00001.html for template. If the release is exciting, tweet it on twitter!

  14. Merge maintenance branch into main.

    It is the best timing to merge just after release.