Skip to content

Commit

Permalink
doc: clarify the release process adr (#168)
Browse files Browse the repository at this point in the history
  • Loading branch information
@aroberts87
aroberts87 authored Oct 2, 2023
1 parent 3818f90 commit f1de03d
Showing 1 changed file with 65 additions and 59 deletions.
124 changes: 65 additions & 59 deletions docs/decisions/adr-0001-release-process.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,116 +17,126 @@ be defined:
## Decision
### Release Cadence
#### Regular Releases
The Ansible Collection will be release at the same time as the Sysdig Agent.
This will allow users to upgrade the Ansible Collection and be able to deploy
the newly released version of the Agent with existing playbooks.
The Ansible Collection will be released simultaneously with the Sysdig Agent.
This will allow users an easy path to upgrade their environments using existing
playbooks.

Releasing simultaneously with the Agent also means that all new feature
development done to the Collection between Agent releases will be 'held' until
the next Agent release. This method ensures that feature development on the
Collection to support new Agent functionality does not need to be held back on
branches and merged all at the same time when the Agent is released. By
allowing new content to merge to `main` when completed we will reduce the
operational complexities encountered at release time.
Releasing on the same cadence as the Agent also means that development on the
Collection that occurs between Agent releases is always open and new content is
free to land on the `main` branch without fear releasing content in the Collection
before the Agent that supports that content. By allowing new content to merge
to `main` as it is completed, we reduce the operational complexities encountered
at release time that would otherwise arise from a flurry of merges right before a
new release branches.

#### Hotfixes
Unlike regular releases, hotfix releases will be created and released whenever
they are required without hesitation.

### Branching Strategy
All development in the Collection will be done on the `main` branch. That is to say,
all new features and bugfixes must hit `main` before being cherry-picked to another branch.

#### Major Releases
The Ansible Collection will do all development on the `main` branch. All new
commits must first be merged to the `main` branch before anywhere else. When
a new major version release is to be made a corresponding branch will be
created with the following format, `releases/<major_version>.<minor_version>`.
When a new major version release is to be made a corresponding branch will be
created with the following format, `releases/<major_version>.0`.
Prior to creating the release branch, a commit setting the upcoming Collection version in
the [galaxy.yaml](https://github.com/sysdiglabs/agent-ansible-collection/blob/main/galaxy.yml)
file must be made.
```mermaid
gitGraph:
commit
commit
commit id: "chore: set version to 1.0.0"
branch releases/1.0
checkout releases/1.0
commit tag: "1.0.0"
commit tag: "1.0.0-rc1"
checkout main
commit
commit
branch releases/2.0
checkout releases/2.0
commit tag: "2.0.0"
commit id: "fix: rc1 bug"
checkout releases/1.0
cherry-pick id: "fix: rc1 bug" tag: "1.0.0"
```

#### Minor Releases
Minor releases will get their own branches similar to major release, with the
notable change of the branch being created with the major release branch as
its base instead of `main`. Bugfixes and new minor features that require minor
releases must first be merged to the `main` branch before being cherry-picked
to the new minor release branch.
Minor releases will get their own branches off of the `main` branch similar to the major
releases, and will follow the same `releases/<major_version>.<minor_version>` naming scheme.
This will allow easier code management as opposed to branching off of the major
release branch by reducing the number of cherry-picks required for either new content or
bugfixes coming in after the minor release has branched.
Similarly to the major releases, when a new minor release branch is created, a commit adjusting
the Collection version in the [galaxy.yaml](https://github.com/sysdiglabs/agent-ansible-collection/blob/main/galaxy.yml)
file must be made.
```mermaid
gitGraph:
commit
commit
commit id: "chore: set version to 1.0.0"
branch releases/1.0
checkout releases/1.0
commit tag: "1.0.0"
commit tag: "1.0.0-rc1"
checkout main
commit id: "fix: 1.0.0-rc1 bug"
checkout releases/1.0
cherry-pick id: "fix: 1.0.0-rc1 bug" tag: "1.0.0"
checkout main
commit
commit
commit id: "feat(...): minor feature"
checkout releases/1.0
commit id: "chore: set version to 1.1.0"
branch releases/1.1
cherry-pick id: "feat(...): minor feature" tag: "1.1.0"
checkout releases/1.1
commit tag: "1.1.0-rc1"
checkout main
commit
branch releases/2.0
checkout releases/2.0
commit tag: "2.0.0"
commit id: "fix: 1.1.0-rc1 bug"
checkout releases/1.1
cherry-pick id: "fix: 1.1.0-rc1 bug" tag: "1.1.0-rc2"
checkout main
commit id: "feat: unrelated feat"
commit id: "fix: 1.1.0-rc2 bug"
checkout releases/1.1
cherry-pick id: "fix: 1.1.0-rc2 bug" tag: "1.1.0"
```

#### Hotfix Releases
Hotfix releases will not get their own branches, but will instead rely on
placing a new release tag with the appropriate hotfix version on the relevant
branch. When a hotfix is needed the fix will first be merged to `main`, then
will be cherry-picked to the appropriate major release branch. The process will
look like the following:
will be cherry-picked to the appropriate major and/or minor release branch(es).
Along with the hotfix content, a commit adjusting the version field in the
Collection's [galaxy.yaml](https://github.com/sysdiglabs/agent-ansible-collection/blob/main/galaxy.yml)
file must be made on the relevant release branch(es).

The process will look like the following:
```mermaid
gitGraph:
commit
commit
commit id: "chore: set version to 1.0.0"
branch releases/1.0
commit tag: "1.0.0"
checkout main
commit
commit
commit id: "chore: set version to 2.0.0"
branch releases/2.0
commit tag: "2.0.0"
checkout main
commit id: "fix(...): hotfix"
checkout releases/1.0
commit id: "chore: set version to 1.0.1"
cherry-pick id: "fix(...): hotfix" tag: "1.0.1"
checkout main
checkout releases/2.0
commit id: "chore: bump version to 2.0.1"
cherry-pick id: "fix(...): hotfix" tag: "2.0.1"
```

### Release Candidate Process
The release process will involve the generation and testing of release
candidates. Release candidates of the Collection will be indicated by the use
of a special release candidate tag. The format of such tags will be
`<major_version>.<minor_version>.<patch_version>-rc<RC number>`. Concretely, an example of
such a tag is `1.0.0-rc1`.
```mermaid
gitGraph:
commit
commit
branch releases/1.0
commit tag: "1.0.0-rc1"
```
The number following `rc` will
increment by one for each subsequent release candidate and a new tag will be
placed accordingly
of a special release candidate tag. The format of such tags is defined in
[adr-0002](https://github.com/sysdiglabs/agent-ansible-collection/blob/main/docs/decisions/adr-0002-tag-naming.md).
The number following `rc` will increment by one for each subsequent release candidate
and a new tag will be placed accordingly
```mermaid
gitGraph:
commit
commit
commit id: "chore: set version to 1.0.0"
branch releases/1.0
commit tag: "1.0.0-rc1"
checkout main
Expand All @@ -143,7 +153,7 @@ to ingest the Collection content by the Ansible Galaxy.
```mermaid
gitGraph:
commit
commit
commit id: "chore: set version to 1.0.0"
branch releases/1.0
commit tag: "1.0.0-rc1"
checkout main
Expand All @@ -153,7 +163,3 @@ to ingest the Collection content by the Ansible Galaxy.
checkout releases/1.0
cherry-pick id:"fix(...): bugfix" tag: "1.0.0-rc2, 1.0.0"
```

## Consequences
* Any new content added to the Collection will not be available to users until
the next major release.

0 comments on commit f1de03d

Please sign in to comment.