diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index cfffda0c6c..14ca51f234 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -25,6 +25,6 @@ jobs: Example manifests to deploy the external cloud provider can be found [here](https://github.com/kubernetes/cloud-provider-aws/tree/master/manifests). ## CHANGELOG - See [CHANGELOG](https://github.com/kubernetes/cloud-provider-aws/blob/master/CHANGELOG.md) for full list of changes. + See [CHANGELOG](https://github.com/kubernetes/cloud-provider-aws/blob/master/docs/CHANGELOG.md) for full list of changes. draft: false prerelease: false diff --git a/.gitignore b/.gitignore index b08375e890..53f9cfd10d 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ .vscode/ docs/book/_book/ +site/ diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 120000 index bc5bca726f..0000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1 +0,0 @@ -changelogs/CHANGELOG-0.1.md \ No newline at end of file diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/RELEASE.md b/docs/RELEASE.md new file mode 100644 index 0000000000..2c76dcf575 --- /dev/null +++ b/docs/RELEASE.md @@ -0,0 +1,81 @@ +# AWS Cloud Provider Release Process + +NOTE: Your GitHub account must have the required permissions and you must have generated a GitHub token. + +## Choosing the release version + +Using semantic versioning, pick a release number that makes sense by bumping the major, minor or patch release version. If its a major or minor release (backwards incompatible changes, and new features, respectively) then you will want to start this process with an alpha release first. Here are some examples: + +Bumping a minor version after releasing a new feature: +``` +v1.4.5 -> v1.5.0-alpha.0 +``` + +After testing and allowing some time for feedback on the alpha, releasing v1.5.0: +``` +v1.4.5 -> v1.5.0 +``` + +New patch release: +``` +v1.5.3 -> v1.5.4 +``` + +New major version release with two alpha releases: +``` +v1.6.2 -> v2.0.0-alpha.0 + -> v2.0.0-alpha.1 + -> v2.0.0 +``` + +## Choosing the release branch +You also might need to create a release branch, if it doesn't already exist, if this release requires backporting changes to an older major or minor version. For example, in the case that we are backporting a fix to the v0.5 release branch, and we have a v0.6 release branch (which we don't at the time of writing), then we would do the following: + +1. Create the release branch (named release-0.5) if it doesn't exist from the last v0.5.x tagged release (or check it out if it already exists). +2. Cherry-pick the necessary commits onto the release branch. +3. Follow the instructions below to create the release commit. +4. Create a pull request to merge your fork of the release branch into the upstream release branch (i.e. /cloud-provider-aws/release-0.5 -> kubernetes/cloud-provider-aws/release-0.5). + +## Create the release commit + +### Generate the CHANGELOG +We need to generate the CHANGELOG for the new release by running `./hack/changelog.py`. You need to pass previous release tag to generate the changelog. + +``` +python3 hack/changelog.py --token $GITHUB_TOKEN --changelog-file docs/CHANGELOG.md --section-title v1.20.0-alpha.1 --range v1.19.0-alpha.1.. +``` +This will prepend the changes to the CHANGELOG.md file. + +### Update the README +Search for any references to the previous version on the README, and update them if necessary. You'll need to update the compatibility table the least. + +### Update the deployment files +1. Update Helm values + - `charts/aws-cloud-controller-manager/Chart.yaml` + - `charts/aws-cloud-controller-manager/values.yaml` +1. Update ` manifests/aws-cloud-controller-manager-daemonset.yaml` + +### Send a release PR +At this point you should have all changes required for the release commit. Verify the changes via `git diff` and send a new PR with the release commit against the release branch. Note that if it doesn't exist, you'll need someone with write privileges to create it for you. + +## Tag the release + +Once the PR is merged, pull the release branch locally and tag the release commit with the release tag. You'll need push privileges for this step. + +``` +git checkout release-0.7 +git pull upstream release-0.7 +git tag v0.7.0 +git push upstream v0.7.0 +``` + +## Verify the release on GitHub + +The new tag should trigger a new Github release. Verify that it has run by going to [Releases](https://github.com/kubernetes/cloud-provider-aws/releases). Then, click on the new version and verify all assets have been created: + +- Source code (zip) +- Source code (tar.gz) + +## Merge the release commit to the main branch + +Once the images are promoted, send a PR to merge the release commit to the main branch. diff --git a/hack/changelog.py b/hack/changelog.py index 9d7a6ef016..c2adc56b58 100644 --- a/hack/changelog.py +++ b/hack/changelog.py @@ -8,6 +8,7 @@ # Generate a changelog from github commit history (pull request merges) + class ChangelogGenerator: def __init__(self, github_repo, token): self._github = Github(token) @@ -17,20 +18,26 @@ def generate(self, pr_id): pr = self._github_repo.get_pull(pr_id) return f'{pr.title} ([#{pr_id}]({pr.html_url}), @{pr.user.login})' + def git_log(range=''): process = Popen(['git', 'log', range], stdout=PIPE, stderr=PIPE) stdout, stderr = process.communicate() if process.returncode != 0: - raise RuntimeError(f'git log returned {process.returncode} and failed with error: {stderr.decode("utf-8")}') + raise RuntimeError( + f'git log returned {process.returncode} and failed with error: {stderr.decode("utf-8")}') return stdout.decode("utf-8") + if __name__ == '__main__': parser = argparse.ArgumentParser(prog='changelog') parser.add_argument('--token', help='Your github token.') - parser.add_argument('--changelog-file', help='The path to the changelog output file.') - parser.add_argument('--print-only', action='store_true', help='Only print the output.') + parser.add_argument('--changelog-file', + help='The path to the changelog output file.') + parser.add_argument('--print-only', action='store_true', + help='Only print the output.') parser.add_argument('--range', help='The range of commit logs to inspect in the repository. You can (and should) use tags here. Example: v5..v10 (This argument is passed to git log, so read the git log documentation for clarification.') - parser.add_argument('--section-title', help='The title for the section in the changelog that is generated') + parser.add_argument( + '--section-title', help='The title for the section in the changelog that is generated') args = parser.parse_args() if args.section_title is None: @@ -48,7 +55,7 @@ def git_log(range=''): logs = git_log(args.range) - changelog = f'{args.section_title}\n' + changelog = f'## {args.section_title}\n' g = ChangelogGenerator('kubernetes/cloud-provider-aws', args.token) for pr_match in re.finditer(r'Merge pull request #(\d+)', logs): pr_id = int(pr_match.group(1)) @@ -58,7 +65,8 @@ def git_log(range=''): print(changelog) sys.exit(0) else: - with open(args.changelog_file, 'r+') as f: + with open(args.changelog_file, 'r') as f: existing = f.read() + with open(args.changelog_file, 'w') as f: f.write(changelog) f.write(existing) diff --git a/mkdocs.yml b/mkdocs.yml index 6aee7499f4..dfa8ee9bd4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,10 +3,19 @@ docs_dir: ./docs site_description: Documentation for AWS Cloud Provider for Kubernetes repo_name: kubernetes/cloud-provider-aws/ repo_url: https://github.com/kubernetes/cloud-provider-aws/ -theme: material nav: - - README.md - - prerequisites.md - - credential_provider.md - - getting_started.md - - development.md + - 'Home': README.md + - 'User Guide': + - prerequisites.md + - credential_provider.md + - getting_started.md + - 'Development': + - 'Running the Cloud Provider': development.md + - 'Release Process': RELEASE.md + - Changelog: CHANGELOG.md + +theme: + name: material + features: + - navigation.tabs + - navigation.sections