= How to perform a semi-automatic release =

== Prerequisities ==

* System with `python3.6` or greater, installed https://pypi.python.org/pypi/PyGithub/1.35[PyGithub] module.
* A GitHub token - get one on https://github.com/settings/tokens. Choose `repo` scope.

== Process ==

. Clone a clean `openscap` repository:

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

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

. 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), but e.g. the `latest_fedora` and `latest_rhel` may need to be updated if work on a distribution with new version has begun.

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

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

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

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

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

. Build OpenSCAP for Windows
+
--
The Windows build process is described in link:../docs/developer/developer.adoc[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 https://github.com/PyGithub/PyGithub/pull/525
* Full Jenkins integration.