Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update release documentation about release_helper.py script #10502

Merged
merged 3 commits into from
Apr 28, 2023
Merged

Update release documentation about release_helper.py script #10502

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c2221ed
Update release documentation about release_helper
marcusburghardt Apr 27, 2023
defe42f
Apply suggestions from code review
marcusburghardt Apr 28, 2023
3c6c0f8
Style Guide alignment: one sentence per line
marcusburghardt Apr 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 92 additions & 3 deletions docs/release_process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,52 @@
How to Perform An Upstream Release (GitHub)
===========================================

# Automation of Release Tasks

In line with this release process documentation, there is a script designed to automate the tasks described in this document as much as possible.
While any task can be performed manually, it is highly recommended to use the `release_helper.py` script during the release process in order to increase the efficiency and be less prone to errors.

The script interacts with the Github API, so an [API token](https://github.com/settings/tokens) is required for most tasks.
Instructions for generating a Github API token can be found directly in the [Github documentation](https://docs.github.com/), but some hints are also provided by the script.

The `release_helper.py` script can also be used to check the current status of the project regarding releases:

```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content stats
```

There is an example usage of `release_helper.py` shown for each automated task throughout the document.
Anyway, here's a cheat sheet for quicker reference:

```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --contributors
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --branch
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --milestone
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --issues
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --bump-version
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release --message
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release --tag
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content cleanup --branch
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content finish --message
```

## How to Contribute

This script was created targeting automation of boring tasks and reduction of human errors while allowing release process to be executed much faster with a lower knowledge curve.

There is still space for improvement and any contribution is welcome. Here are some ideas to start contributing:
* Include an option to automate the process of updating the **stable** branch
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I am looking at those ideas, wouldn't it be better to create them as upstream issues? I am not sure that they will be discovered here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is also a good idea to create them as upstream issues. Some improvements are relatively simple. I will review them soon (before the next release). After this review, if something remains in this list or if new ideas appear, I can file upstream issues for them.

* Improve the messages to include the name of maintainer
* Thanks [Matthew](https://github.com/ComplianceAsCode/content/pull/10076#discussion_r1165956665) for this idea.
* Introduce a checklist of steps during the release
* Something similar to **stats** but related to the steps in process.
* Some steps depend on other steps and may be concluded after some days. It would be great to know precisely in which step of the process we are.


# Stabilization Phase

Before each release we initiate a stabilization period which is typically two weeks long.
A stabilization branch is branched from master and more extensive testing is done on the content.
A stabilization branch is branched from master and more extensive tests are done on the content.
The goal is to have space and time to find and fix issues before the release.
Everyone is welcome to test the stabilization branch and propose fixes.

Expand All @@ -26,19 +68,34 @@ the following command:
- Make a commit send a PR to the `master` branch.
- Reference: https://github.com/ComplianceAsCode/content/pull/9843

Using `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --contributors
```

### Creating the Stabilization Branch

- Create a new branch called **stabilization-vX.Y.Z** where **X.Y.Z** is the version of upstream
release to be created.
- For example, if the last released version was **0.1.64**, the branch should be named as
`stabilization-v0.1.65`

Using `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --branch
```

### Creating the New Milestone

- Create a new Milestone called **X.Y.Z**, where **X.Y.Z** is the version of future upstream release.
- For example, if you have just created the `stabilization-v0.1.65` branch in order to start
the stabilization phase for **0.1.65**, the new Milestone should be `0.1.66`.

Using `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --milestone
```

### Updating Open PRs and Issues

- All **Pull Requests** and **Issues** which are open at the moment the stabilization branch is
Expand All @@ -60,13 +117,25 @@ Milestone must be updated to refer the next release.
> **_NOTE:_** It is still possible to add items to the closed Milestone. Just select it in the
`closed` tab.

Using `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --issues
```

### Bumping the Version

- Open a PR to bump the version of `CMakeLists.txt` on the **master** branch.
- For example, when the `stabilization-v0.1.65` is created, the line `set(SSG_PATCH_VERSION 65)`
must be updated to `set(SSG_PATCH_VERSION 66)` in the `CMakeLists.txt` file
- Reference: https://github.com/ComplianceAsCode/content/pull/9857

Using `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release_prep --bump-version
```

## During the stabilization

### Announcing the Start of Stabilization Period

- Announce the start of stabilization period on the following communication channels:
Expand Down Expand Up @@ -97,7 +166,10 @@ Milestone must be updated to refer the next release.
Regards,
```

## During the stabilization
This message can be completely created using the `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release --message
```

### Bug Fixes
- Run whatever extra tests you have and report bugs as Upstream issues using the
Expand Down Expand Up @@ -202,7 +274,12 @@ git push --tags
> **_NOTE:_** In case there is a need to run the job again, delete the release draft and run the
GitHb Action again.

# Clean Up
Using `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content release --tag
```

### Updating the *stable* branch

- Update the **stable** branch to point to the new release:
```
Expand All @@ -215,11 +292,18 @@ git merge stabilization-vX.Y.Z
git push
```

# Clean Up

- Delete the **stabilization-vX.Y.Z** branch.
```
git push upstream --delete stabilization-vX.Y.Z
```

Using `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content cleanup --branch
```

# Announce It!

- Announce the new release on the following communication channels:
Expand Down Expand Up @@ -267,6 +351,11 @@ git push upstream --delete stabilization-vX.Y.Z
Regards,
```

This message can be completely created using the `release_helper.py` script:
```bash
./release_helper.py -c ~/secret.ini -r ComplianceAsCode/content finish --message
```

# Downstream Build

It is good for the community when the packages are also updated and released with the latest
Expand Down