Skip to content

Commit 5110cfb

Browse files
TinaMorTinaMor
committed
Add a MAINTAINERS_GUIDE.md file
1 parent c1d6849 commit 5110cfb

File tree

4 files changed

+265
-26
lines changed

4 files changed

+265
-26
lines changed

‎build/hacks/get-newversion.ps1‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<#
2+
.SYNOPSIS
3+
Get the new version number for the release.
4+
5+
.DESCRIPTION
6+
Given a release version, this script will recursively check for a valid version number
7+
by checking the PowerShell Gallery.
8+
9+
.PARAMETER Version
10+
The version number to check for. This should be a valid semantic version number.
11+
Example: 1.2.3
12+
13+
.PARAMETER Prerelease
14+
The pre-release tag to check for. This should be a valid semantic version pre-release tag.
15+
Example: alpha2, beta0, rc0
16+
17+
.PARAMETER ReleaseType
18+
The type of release to check for. This should be one of the following:
19+
major, minor, patch
20+
21+
.PARAMETER MaxPrerelease
22+
The maximum number of pre-release tags to check for. This is used to limit the number of
23+
iterations when checking for a valid version number. Default is 20.
24+
For example, if the current version is 1.2.3-alpha2 and the next version is 1.2.3-alpha3,
25+
this will check for 20 pre-release tags: alpha3, alpha4, ..., alpha20.
26+
27+
When the maximum number of pre-release tags is reached, the script will stop checking and increment
28+
the version number based on the release type.
29+
30+
When MaxPrerelease is set to 0 (or less), the script will not check for pre-release tags and will
31+
increment the version number based on the release type.
32+
33+
.EXAMPLE
34+
.\get-newversion.ps1 -Version 1.2.3 -Prerelease alpha2 -ReleaseType minor
35+
36+
This will check for the next version number based on the provided version, pre-release tag, and release type.
37+
#>
38+
39+
[CmdletBinding()]
40+
param (
41+
[Parameter(Mandatory = $true)]
42+
[version]$Version,
43+
44+
[Parameter(Mandatory = $false)]
45+
[string]$Prerelease,
46+
47+
[Parameter(Mandatory = $true)]
48+
[ValidateSet("major", "minor", "patch")]
49+
[string]$ReleaseType,
50+
51+
[Parameter(Mandatory = $false)]
52+
[int]$MaxPrerelease = "20"
53+
)
54+
55+
$ErrorActionPreference = "Stop"
56+
57+
function Update-SemverTag($Semver, $ReleaseType) {
58+
switch ($ReleaseType) {
59+
"major" { return [version]::new($Semver.Major + 1, 0, 0) }
60+
"minor" { return [version]::new($Semver.Major, $Semver.Minor + 1, 0) }
61+
"patch" { return [version]::new($Semver.Major, $Semver.Minor, $Semver.Build + 1) }
62+
}
63+
}
64+
65+
function Get-PrereleaseValue($PrereleaseTag) {
66+
$match = [regex]::Match($PrereleaseTag, "(.*?)(\d+)$")
67+
return [int]$match.Groups[2].Value + 1
68+
}
69+
70+
function Update-Prerelease($PrereleaseTag) {
71+
$match = [regex]::Match("$PrereleaseTag", "(.*?)(\d+)$")
72+
$prefix = [string]$match.Groups[1].Value
73+
$number = [int]$match.Groups[2].Value
74+
return "$prefix" + "$($number + 1)"
75+
}
76+
77+
function Test-ModuleVersion($ModuleVersion) {
78+
$PublishedVersions = Find-Module -AllowPrerelease `
79+
-Name containers-toolkit `
80+
-RequiredVersion "$ModuleVersion" `
81+
-ErrorAction SilentlyContinue | Where-Object { $_.Version -eq $ModuleVersion }
82+
return $PublishedVersions
83+
}
84+
85+
while ($true) {
86+
$ModuleVersion = "${Version}-${Prerelease}".TrimEnd("-")
87+
Write-Host "Checking for module version: $ModuleVersion" -ForegroundColor Magenta
88+
89+
$PublishedVersions = Test-ModuleVersion $ModuleVersion
90+
if (-not $PublishedVersions) {
91+
Write-Host "Module version $ModuleVersion is not published." -ForegroundColor Magenta
92+
return $ModuleVersion
93+
}
94+
95+
# Find a pre-release tag that is not published
96+
while ($Prerelease -and ($MaxPrerelease -gt 0) -and ($PublishedVersions.Version -match "$Prerelease")) {
97+
$Prerelease = Update-Prerelease $Prerelease
98+
$ModuleVersion = "${Version}-${Prerelease}"
99+
100+
Write-Host "Incrementing pre-release tag: $ModuleVersion" -ForegroundColor Magenta
101+
$PublishedVersions = Test-ModuleVersion $ModuleVersion
102+
if (-not $PublishedVersions) {
103+
Write-Host "Module version $ModuleVersion is not published." -ForegroundColor Magenta
104+
return $ModuleVersion
105+
}
106+
107+
$MaxPrerelease -= 1
108+
}
109+
110+
$Version = Update-SemverTag $Version $ReleaseType
111+
}

‎build/pipeline/release.yml‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎build/scripts/release/MAINTAINERS_GUIDE.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
## Creating a Containers-Toolkit release
2+
3+
> [!IMPORTANT]
4+
> **It is recommended to test with pre-release versions before creating a final release.**
5+
> The PowerShell Gallery does not support permanent deletion of packages. If the module version already exists, you will need to increment the version number
6+
7+
### Create a GitHub tag
8+
9+
1. Get the new module version:
10+
11+
To choose the new version, you can use the [Semantic Versioning](https://semver.org/) scheme. The version number is in the format `X.Y.Z`, where:
12+
- `X` is the *major* version number. Indicates significant **changes that may break backward compatibility** with previous versions (e.g., 1.0.0 to 2.0.0).
13+
- `Y` is the *minor* version number. Represents **new features/ functionality** that are backward compatible (e.g., 1.0.0 to 1.1.0).
14+
- `Z` is the *patch* version number. Refers to **bug fixes or minor changes** that do not affect functionality or compatibility (e.g., 1.0.0 to 1.0.1).
15+
16+
```PowerShell
17+
$NEW_VERSION = "<new version>" # e.g. 1.0.0
18+
```
19+
20+
If this is pre-release, concatenate the pre-release version to the module version. The pre-release version can be `-rc0`, `-beta0`, `-alpha0`, etc.
21+
22+
```PowerShell
23+
$PRERELEASE_TAG = "<pre-release version>" # e.g. -rc0, -beta0, -alpha0
24+
```
25+
26+
Get the release version and tag:
27+
28+
```PowerShell
29+
$RELEASE_VERSION = "${NEW_VERSION}-${PRERELEASE_TAG}".TrimEnd("-")
30+
$RELEASE_TAG = "v${RELEASE_VERSION}"
31+
```
32+
33+
> [!IMPORTANT]
34+
> Ensure that the new version number is not already used in the [PowerShell Gallery][ctk-psg].
35+
> If the version already exists, you will need to increment the version number.
36+
> The PowerShell Gallery does not support permanent deletion of packages.
37+
> Use the `Find-Module` command to check if the version already exists.
38+
>
39+
> ```PowerShell
40+
> Find-Module -Name containers-toolkit -AllowPrerelease -RequiredVersion "$RELEASE_VERSION" | Where-Object { $_.Version -eq $RELEASE_VERSION }
41+
> ```
42+
> Alternatively, you can use the [build/hacks/get-newversion.ps1](../../hacks/get-newversion.ps1) script to get the new version number.
43+
>
44+
> ```PowerShell
45+
> $RELEASE_TAG = build/hacks/get-newversion.ps1 -Version $NEW_VERSION -Prerelease $PRERELEASE_TAG -ReleaseType "major"
46+
> ```
47+
48+
49+
1. Create a new branch from the main branch.
50+
51+
```bash
52+
$BRANCH_NAME = "release/$RELEASE_TAG"
53+
git checkout -b "$BRANCH_NAME"
54+
```
55+
56+
1. Cherry-pick the changes to a new branch from the main branch. The new branch name should be `release/X.Y.Z`, where `X.Y.Z` is the new version number.
57+
58+
- Identify the commit hashes you want to include. You can find them using:
59+
60+
```bash
61+
git log
62+
```
63+
64+
- Cherry-pick the commits to the new branch. You can cherry-pick multiple commits at once by specifying their hashes separated by spaces.
65+
66+
```bash
67+
git cherry-pick <commit_hash_1> <commit_hash_2> <commit_hash_3>
68+
```
69+
70+
- Resolve Any Conflicts (If Necessary)
71+
72+
If there are any conflicts during the cherry-pick process, Git will pause and allow you to resolve them. After resolving the conflicts, you can continue the cherry-pick process with:
73+
74+
```bash
75+
git status # Identify conflicts
76+
# Resolve conflicts in your preferred editor
77+
git add .
78+
git cherry-pick --continue
79+
```
80+
81+
1. Update the module version in the README.md file
82+
83+
*NOTE: Only update the version number in the README.md file for the latest release and not for pre-releases._*
84+
85+
1. Create a tag and a release in GitHub.
86+
87+
```bash
88+
git tag --sign "$RELEASE_TAG" -m "Release $RELEASE_TAG"
89+
git push upstream "$BRANCH_NAME" --tags
90+
```
91+
92+
> [!TIP]
93+
> To delete an existing tag, use the following command:
94+
>
95+
> ```bash
96+
> git tag --delete "$RELEASE_TAG"
97+
> git push upstream :refs/tags/"$RELEASE_TAG"
98+
> ```
99+
100+
<!-- > [!NOTE]
101+
> <https://github.com/orgs/community/discussions/48462>
102+
> As of February 2025, GitHub does not have the option to only create a tag without creating a release. We therefore delete the release after creating the tag.
103+
104+
```bash
105+
gh release delete -y $RELEASE_TAG
106+
``` -->
107+
108+
### Create a release using the ADO release pipeline
109+
110+
Releases are created using the Containers-Toolkit ADO release pipeline. The release pipeline is triggered by the creation of a new release branch in GitHub. However, you can also create a [release manually](#manual-release).
111+
112+
#### Manual release
113+
114+
1. In the artifact section, select the `Default Branch` to use for the release.
115+
116+
*The branch created in step 2 should be selected.*
117+
118+
The release pipeline uses the branch name to determine the version number. The version number is derived from the branch name by removing the `release/` prefix.
119+
120+
For example:
121+
122+
| Branch Name | Version Number |
123+
|----------------------|----------------|
124+
| `release/v1.0.0` | `v1.0.0` |
125+
| `release/v1.0.0-rc0` | `v1.0.0-rc0` |
126+
127+
1. Create a new release.
128+
129+
This publishes the module to the [PowerShell Gallery][ctk-psg] and creates a new release in GitHub.
130+
131+
1. Verify the PowerShell Gallery release:
132+
133+
```PowerShell
134+
Find-Module -Name containers-toolkit -AllVersions -AllowPrerelease
135+
```
136+
137+
> [!IMPORTANT]
138+
> If the module has any issues, unlist the version in the [PowerShell Gallery][ctk-psg].
139+
140+
1. Go to the created release in GitHub and do the following:
141+
1. update the release notes.
142+
2. Verify that all files have been uploaded correctly and the scripts are signed. There should be three files:
143+
- *containers-toolkit-<RELEASE_TAG>.tar.gz*
144+
- *containers-toolkit-<RELEASE_TAG>.zip*
145+
- *containers-toolkit-<RELEASE_TAG>.SHA256*
146+
3. By default, the release is marked as a draft. To publish the release:
147+
- Click on the **Edit** button.
148+
- If it is a pre-release, check the **Set as a pre-releasee** checkbox.
149+
- Finally, click on the **Publish release** button.
150+
151+
[ctk-psg]: https://www.powershellgallery.com/packages/containers-toolkit

‎build/scripts/release/get-versionfromBranch.ps1‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@ switch ($VersionSplit.Count) {
3737
$ReleaseVersion = "$version"
3838
}
3939
2 {
40-
$PreleaseTag = $VersionSplit[1].ToLower()
41-
$ReleaseVersion = "$version-$PreleaseTag"
40+
$PrereleaseTag = $VersionSplit[1].ToLower()
41+
$ReleaseVersion = "$version-$PrereleaseTag"
4242
}
4343
Default {
4444
Write-Error $ValidationError
@@ -48,7 +48,7 @@ switch ($VersionSplit.Count) {
4848
# Generate the version object
4949
$result = [PSCustomObject]@{
5050
Version = "$version"
51-
PreleaseTag = $PreleaseTag
51+
Prerelease = $PrereleaseTag
5252
ReleaseVersion = $ReleaseVersion
5353
ReleaseTag = "v$ReleaseVersion"
5454
}

0 commit comments

Comments
 (0)