GitHub-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Update RELEASE.adoc for release automation

pull/15055/head
Steve Riesenberg 2 years ago
parent
ec1b15ed68
commit
f74aeaffa1
No known key found for this signature in database
GPG Key ID: 3D0169B18AB8F0A9
1 changed files with 135 additions and 149 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 284
      RELEASE.adoc

284
RELEASE.adoc
Unescape View File

@ -1,279 +1,265 @@
= Release Process = Release Process
The release process for Spring Security is partially automated. The following table outlines which steps are automated and which are manual. Follow the links to read about each step. The release process for Spring Security is entirely automated via the https://github.com/spring-io/spring-security-release-tools/blob/main/release-plugin/README.adoc[Spring Security Release Plugin] and https://github.com/spring-io/spring-security-release-tools/tree/main/.github/workflows[reusable workflows].
The following table outlines the steps that are taken by the automation.
[cols="1,1"] WARNING: The `5.8.x` branch does not have all of the improvements from the `6.x.x` branches. See "Status (5.8.x)" for which steps are still manual.
In case of a failure, you can follow the links below to read about each step. See <<frequently-asked-questions,FAQ>> for troubleshooting tips.
[cols="1,1,1"]
|=== |===
| Step | Status | Step | Status (5.8.x) | Status (6.0.x+)
| <<update-dependencies>> | <<update-dependencies>>
| :x: manual | :white_check_mark: automated
| :white_check_mark: automated
| <<check-all-issues-are-closed>> | <<check-all-issues-are-closed>>
| :white_check_mark: automated (scheduled release will abort if any issues are open) | :white_check_mark: automated
| :white_check_mark: automated
| <<update-release-version>> | <<update-release-version>>
| :white_check_mark: automated | :white_check_mark: automated
| <<update-antora-version>>
| :white_check_mark: automated | :white_check_mark: automated
| <<build-locally>> | <<tag-release>>
| :x: manual (when updating dependencies) | :white_check_mark: automated
| :white_check_mark: automated
| <<push-release-commit>> | <<push-release-commit>>
| :white_check_mark: automated | :white_check_mark: automated
| :white_check_mark: automated
| <<announce-release-on-slack>> | <<build-locally>>
| :white_check_mark: automated
| :white_check_mark: automated | :white_check_mark: automated
| <<tag-release>> | <<announce-release-on-slack>>
| :white_check_mark: automated
| :white_check_mark: automated | :white_check_mark: automated
| <<update-to-next-development-version>> | <<update-to-next-development-version>>
| :white_check_mark: automated | :white_check_mark: automated
| :white_check_mark: automated
| <<update-version-on-project-page>> | <<update-version-on-project-page>>
| :x: manual | :x: manual
| :white_check_mark: automated
| <<update-release-notes-on-github>> | <<update-release-notes-on-github>>
| :white_check_mark: automated | :white_check_mark: automated
| :white_check_mark: automated
| <<close-create-milestone,Close milestone>> | <<close-create-milestone,Close milestone>>
| :x: manual (move issues to new milestone before release) | :x: manual
| :white_check_mark: automated
| <<close-create-milestone,Create milestone>> | <<close-create-milestone,Create milestone>>
| :white_check_mark: automated (if not already created) | :white_check_mark: automated
| :white_check_mark: automated
| <<announce-release-on-other-channels>> | <<announce-release-on-other-channels>>
| :x: manual | :x: manual
| :x: manual
|=== |===
*When should I update dependencies manually?* Dependencies should be updated at the latest the end of the week prior to the release. This is usually the Friday following the 2nd Monday of the month (counting from the first week with a Monday). When in doubt, check the https://github.com/spring-projects/spring-security/milestones[milestones] page for release due dates. [#update-dependencies]
== Update dependencies
*When do scheduled releases occur?* Automated releases are scheduled to occur at *3:15 PM UTC* on the *3rd Monday of the month* (counting from the first week with a Monday).
[NOTE] Dependency versions are managed in the file xref:./gradle/libs.versions.toml[libs.versions.toml] and are automatically updated by xref:./.github/dependabot.yml[dependabot].
The scheduled release process currently runs every Monday but only releases when a release is due. See the performed checks below for more information.
The automated release process occurs on the following branches: [#check-all-issues-are-closed]
== Check all issues are closed
* `main` The first step of a release is to check if there are any open issues remaining in a milestone.
* `6.0.x`
* `5.8.x`
* `5.7.x`
For each of the above branches, the automated process performs the following checks before proceeding with the release: NOTE: A scheduled release will not proceed if there are any open issues.
1. _Check if the milestone is due today._ This check compares the current (SNAPSHOT) version of the branch with available milestones and chooses the first match (sorted alphabetically). If the due date on the matched milestone is *not* today, the process stops. TIP: If you need to prevent a release from occurring automatically, the easiest way to block a release is to add an unresolved issue to the milestone.
2. _Check if all issues are closed._ This check uses the milestone from the previous step and looks for open issues. If any open issues are found, the process stops.
[IMPORTANT] The https://github.com/spring-io/spring-security-release-tools/blob/main/release-plugin/README.adoc#checkMilestoneHasNoOpenIssues[`checkMilestoneHasOpenIssues`] command will check if there are any open issues for the release.
You should ensure all issues are closed or moved to another milestone prior to a scheduled release. Before running the command, replace the following values:
If the above checks pass, the version number is updated (in `gradle.properties` and `antora.yml`) and a commit is pushed to trigger the CI process. * `<next-version>` - Replace with the title of the milestone you are releasing now (i.e. 5.5.0-RC1)
* `<github-personal-access-token>` - Replace with a https://github.com/settings/tokens[GitHub personal access token] that has a scope of `public_repo`. This is optional since you are unlikely to reach the rate limit for such a simple check.
*How do I trigger a release manually?* You can trigger a release manually in two ways: [source,bash]
----
./gradlew checkMilestoneHasOpenIssues -PnextVersion=<next-version> -PgitHubAccessToken=<github-personal-access-token>
----
1. Trigger a release for a particular branch via https://github.com/spring-projects/spring-security/actions/workflows/update-scheduled-release-version.yml[`update-scheduled-release-version.yml`] on the desired branch. The above checks are performed for that branch, and the release will proceed if all checks pass. _This is the recommended way to trigger a release that did not pass the above checks during a regularly scheduled release._ Alternatively, you can manually check using the https://github.com/spring-projects/spring-security/milestones[milestones] page.
2. Trigger releases for all branches via https://github.com/spring-projects/spring-security/actions/workflows/release-scheduler.yml[`release-scheduler.yml`] on the `main` branch. The above checks are performed for each branch, and only releases that pass all checks will proceed.
*When should additional manual steps be performed?* All other automated steps listed above occur during the normal CI process. Additional manual steps can be performed at any time once the builds pass and releases are finished. [#update-release-version]
== Update release version
*What if something goes wrong?* If the normal CI process fails, you can retry by re-running the failed jobs with the "Re-run failed jobs" option in GitHub Actions. If changes are required, you should revert the "Release x.y.z" commit, delete the tag, and proceed manually. If all issues for the release are <<check-all-issues-are-closed,closed>>, the version number is automatically updated using the milestone title.
When performing this step manually, update the version number in `gradle.properties` for the release (for example `5.5.0`) and commit the change using the message "Release x.y.z".
[#update-dependencies] [#tag-release]
== Update dependencies == Tag release
Ensure you have no changes in your local repository. The release will automatically be tagged using the milestone title.
Change to a new branch. It is not required to tag manually.
For example: However, you can perform this step manually by running the following command:
[source,bash] [source,bash]
---- ----
$ git checkout -b 5.5.0-RC1-dependencies git tag 5.5.0
---- ----
Review the rules in build.gradle to ensure the rules make sense. [#push-release-commit]
For example, we should not allow major version updates in a patch release. == Push release commit
Also ensure that all of the exclusions still make sense.
The following Gradle command will update your dependencies creating a commit for each dependency update. During a scheduled release, the release commit will automatically be pushed to trigger a build.
The first invocation of the command will take quite a while (~20 minutes depending on internet speed) to run because it is indexing all the versions of all the dependencies. If performing this step manually, you can push the commit and tag and GitHub actions will build and deploy the artifacts with the following command:
[source,bash] [source,bash]
---- ----
$ ./gradlew updateDependencies git push --atomic origin main 5.5.0
---- ----
Review the commits to ensure that the updated dependency versions make sense for this release. For example, we should not perform a major version update for a patch release. The build will automatically wait for artifacts to be released to Maven Central.
You can get notified manually when uploading is complete by running the following:
[source,bash] [source,bash]
---- ----
$ git log ./scripts/release/wait-for-done.sh 5.5.0
---- ----
If any of the versions don’t make sense, update `build.gradle` to ensure that the version is excluded. [#build-locally]
== Build
Run all the checks: All checks will automatically be performed by the build prior to uploading the artifacts to Maven Central.
If something goes wrong, you can run the build locally using:
[source,bash] [source,bash]
---- ----
$ ./gradlew check ./gradlew check
---- ----
If they don’t work, you can run a git bisect to discover what broke the build. [#update-release-notes-on-github]
Fix any commits that broke the build. == Update release notes on GitHub
Once the release has been uploaded to Maven Central, release notes will automatically be generated and a GitHub release will be created.
To do this manually, you can use the https://github.com/spring-io/spring-security-release-tools/blob/main/release-plugin/README.adoc#generateChangelog[`generateChangelog`] command to generate the release notes by replacing:
Check out the original brach: * `<next-version>` - Replace with the milestone you are releasing now (i.e. 5.5.0)
[source,bash] [source,bash]
---- ----
$ git checkout - ./gradlew generateChangelog -PnextVersion=<next-version>
---- ----
The following command will update the dependencies again but this time creating a ticket for each update and placing `Closes gh-<number>` in the commit. Replacing the following values: Then copy the release notes to your clipboard (your mileage may vary with the following command):
* <github-personal-access-token> - Replace with a https://github.com/settings/tokens[GitHub personal access token] that has a scope of `public_repo`
* <next-version> - Replace with the title of the milestone you are releasing now (i.e. 5.5.0-RC1)
[source,bash] [source,bash]
---- ----
$ ./gradlew updateDependencies -PupdateMode=GITHUB_ISSUE -PgitHubAccessToken=<github-personal-access-token> -PnextVersion=<next-version> cat build/changelog/release-notes.md | xclip -selection clipboard
---- ----
Apply any fixes from your previous branch that were necessary. Finally, create the
https://github.com/spring-projects/spring-security/releases[release on
[#check-all-issues-are-closed] GitHub], associate it with the tag, and paste the generated notes.
== Check all issues are closed
The following command will check if there are any open issues for the ticket. Alternatively, you can run the https://github.com/spring-io/spring-security-release-tools/blob/main/release-plugin/README.adoc#createGitHubRelease[`createGitHubRelease`] command to perform these steps automatically, replacing:
Before running the command, replace the following values:
* <github-personal-access-token> - Replace with a https://github.com/settings/tokens[GitHub personal access token] that has a scope of `public_repo`. This is optional since you are unlikely to reach the rate limit for such a simple check. * `<next-version>` - Replace with the milestone you are releasing now (i.e. 5.5.0)
* <next-version> - Replace with the title of the milestone you are releasing now (i.e. 5.5.0-RC1) * `<branch>` - The name of the branch to be tagged (if the release commit has not already been tagged)
* `<github-personal-access-token>` - Replace with a https://github.com/settings/tokens[GitHub personal access token] that has a scope of `write:org`
[source,bash] [source,bash]
---- ----
$ ./gradlew gitHubCheckMilestoneHasNoOpenIssues -PgitHubAccessToken=<github-personal-access-token> -PnextVersion=<next-version> ./gradlew createGitHubRelease -PnextVersion=<next-version> -Pbranch=<branch> -PcreateRelease=true -PgitHubAccessToken=<github-personal-access-token>
---- ----
Alternatively, you can manually check using https://github.com/spring-projects/spring-security/milestones [#update-version-on-project-page]
== Update version on project page
[#update-release-version]
== Update release version
Update the version number in `gradle.properties` for the release, for example `5.5.0-M1`, `5.5.0-RC1`, `5.5.0`
[#update-antora-version] The build will automatically update the project versions on https://spring.io/projects/spring-security#learn.
== Update antora version To do this manually, you can use the https://github.com/spring-io/spring-security-release-tools/blob/main/release-plugin/README.adoc#createSaganRelease[`createSaganRelease`] and https://github.com/spring-io/spring-security-release-tools/blob/main/release-plugin/README.adoc#deleteSaganRelease[`deleteSaganRelease`] commands using the following parameters:
You will need to update the antora.yml version. * `<next-version>` - Replace with the milestone you are releasing now (i.e. 5.5.0)
If you are unsure of what the values should be, the following task will instruct you what the expected values are: * `<previous-version>` - Replace with the previous release which will be removed from the listed versions (i.e. 5.5.0-RC1)
* `<github-personal-access-token>` - Replace with a https://github.com/settings/tokens[GitHub personal access token] that has a scope of `read:org` as https://spring.io/restdocs/index.html#authentication[documented for spring.io api]
[source,bash] [source,bash]
---- ----
./gradlew :spring-security-docs:antoraCheckVersion ./gradlew createSaganRelease deleteSaganRelease -PnextVersion=<next-version> -PpreviousVersion=<previous-version> -PgitHubAccessToken=<github-personal-access-token>
---- ----
[#build-locally] Alternatively, you can log into Contentful and update the versions manually on the Spring Security project page.
== Build locally
Run the build using
[source,bash] [#close-create-milestone]
---- == Close / Create milestone
$ ./gradlew check
----
[#push-release-commit] The release milestone will be automatically closed once the release is complete.
== Push release commit To proceed manually, perform the following steps:
Push the commit and GitHub actions will build and deploy the artifacts 1. Visit https://github.com/spring-projects/spring-security/milestones[GitHub
If you are pushing to Maven Central, then you can get notified when it’s uploaded by running the following: Milestones] and create a new milestone for the next release version
2. Move any open issues from the existing milestone you just released to the new milestone
3. Close the milestone for the release
[source,bash] NOTE: Remember that scheduled releases <<check-all-issues-are-closed,will not proceed>> if there are still open issues in the milestone.
----
$ ./scripts/release/wait-for-done.sh 5.5.0
----
[#announce-release-on-slack] [#announce-release-on-slack]
== Announce release on Slack == Announce release on Slack
* Announce via Slack on The release will automatically be announced on Slack.
https://pivotal.slack.com/messages/spring-release[#spring-release], If proceeding manually, announce the release on Slack in the channel https://pivotal.slack.com/messages/spring-release[#spring-release], including the keyword `+spring-security-announcing+` in the message.
including the keyword `+spring-security-announcing+` in the message.
Something like: Something like:
.... ....
spring-security-announcing 5.5.0 is available. spring-security-announcing `5.5.0` is available now
....
[#tag-release]
== Tag release
* Tag the release and then push the tag
....
git tag 5.4.0-RC1
git push origin 5.4.0-RC1
.... ....
[#update-to-next-development-version] [#update-to-next-development-version]
== Update to next development version == Update to next development version
* Update `gradle.properties` version to next `+SNAPSHOT+` version, update antora.yml, and then push After the release is complete and artifacts have been uploaded to Maven Central, the build will automatically update to the next development version, commit and push.
If proceeding manually, update the version in `gradle.properties` to the next `+SNAPSHOT+` version with the commit message "Next development version" and then push.
[#update-version-on-project-page] [#announce-release-on-other-channels]
== Update version on project page == Announce release on other channels
The following command will update https://spring.io/projects/spring-security#learn with the new release version using the following parameters
<github-personal-access-token> - Replace with a https://github.com/settings/tokens[GitHub personal access token] that has a scope of `read:org` as https://spring.io/restdocs/index.html#authentication[documented for spring.io api] * Create a blog post on Contentful
<next-version> - Replace with the milestone you are releasing now (i.e. 5.5.0-RC1) * Tweet from https://twitter.com/springsecurity[@SpringSecurity]
<previous-version> - Replace with the previous release which will be removed from the listed versions (i.e. 5.5.0-M3)
[source,bash] [[frequently-asked-questions]]
---- == Frequently Asked Questions
$ ./gradlew saganCreateRelease saganDeleteRelease -PgitHubAccessToken=<github-personal-access-token> -PnextVersion=<next-version> -PpreviousVersion=<previous-version>
----
[#update-release-notes-on-github] *When should I update dependencies manually?* Dependencies should be updated at the latest the end of the week prior to the release. This is usually the Friday following the 2nd Monday of the month (counting from the first week with a Monday). When in doubt, check the https://github.com/spring-projects/spring-security/milestones[milestones] page for release due dates.
== Update release notes on GitHub
Generate the Release Notes replacing: *When do scheduled releases occur?* Automated releases are scheduled to occur at *3:15 PM UTC* on the *3rd Monday of the month* (counting from the first week with a Monday).
* <next-version> - Replace with the milestone you are releasing now (i.e. 5.5.0-RC1) [NOTE]
The scheduled release process currently runs every Monday but only releases when a release is due. See the performed checks below for more information.
---- The automated release process occurs on the following branches:
$ ./gradlew generateChangelog -PnextVersion=<next-version>
----
* Copy the release notes to your clipboard (your mileage may vary with * `main`
the following command) * `6.2.x`
* `6.1.x`
* `6.0.x` (commercial only)
* `5.8.x`
.... For each of the above branches, the automated process performs the following checks before proceeding with the release:
cat build/changelog/release-notes.md | xclip -selection clipboard
....
* Create the 1. _Check if the milestone is due today._ This check compares the current (SNAPSHOT) version of the branch with available milestones and chooses the first match (sorted alphabetically). If the due date on the matched milestone is *not* today, the process stops.
https://github.com/spring-projects/spring-security/releases[release on 2. _Check if all issues are closed._ This check uses the milestone from the previous step and looks for open issues. If any open issues are found, the process stops.
GitHub], associate it with the tag, and paste the generated notes
[#close-create-milestone] [IMPORTANT]
== Close / Create milestone You should ensure all issues are closed or moved to another milestone prior to a scheduled release.
* In If the above checks pass, the version number is updated (in `gradle.properties`) and a commit is pushed to trigger the CI process.
https://github.com/spring-projects/spring-security/milestones[GitHub
Milestones], create a new milestone for the next release version
* Move any open issues from the existing milestone you just released to
the new milestone
* Close the milestone for the release.
[#announce-release-on-other-channels] *How do I trigger a release manually?* You can trigger a release manually in two ways:
== Announce release on other channels
* Create a https://spring.io/admin/blog[Blog] 1. Trigger a release for a particular branch via https://github.com/spring-projects/spring-security/actions/workflows/update-scheduled-release-version.yml[`update-scheduled-release-version.yml`] on the desired branch. The above checks are performed for that branch, and the release will proceed if all checks pass. _This is the recommended way to trigger a release that did not pass the above checks during a regularly scheduled release._
* Tweet from [@SpringSecurity](https://twitter.com/springsecurity) 2. Trigger releases for all branches via https://github.com/spring-projects/spring-security/actions/workflows/release-scheduler.yml[`release-scheduler.yml`] on the `main` branch. The above checks are performed for each branch, and only releases that pass all checks will proceed.
*When should additional manual steps be performed?* All other automated steps listed above occur during the normal CI process. Additional manual steps can be performed at any time once the builds pass and releases are finished.
*What if something goes wrong?* If the normal CI process fails, you can retry by re-running the failed jobs with the "Re-run failed jobs" option in GitHub Actions. If changes are required, you should revert the "Release x.y.z" commit, delete the tag, and proceed manually.

Write Preview
Loading…
Cancel
Save