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.
| Step | Status |
|---|---|
❌ manual |
|
✅ automated (scheduled release will abort if any issues are open) |
|
✅ automated |
|
✅ automated |
|
❌ manual (when updating dependencies) |
|
✅ automated |
|
✅ automated |
|
✅ automated |
|
✅ automated |
|
❌ manual |
|
✅ automated |
|
❌ manual (move issues to new milestone before release) |
|
✅ automated (if not already created) |
|
❌ 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 milestones page for release due dates.
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
|
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:
-
main -
5.8.x -
5.7.x -
5.6.x
For each of the above branches, the automated process performs the following checks before proceeding with the release:
-
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.
-
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
|
You should ensure all issues are closed or moved to another milestone prior to a scheduled release. |
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.
How do I trigger a release manually? You can trigger a release manually in two ways:
-
Trigger a release for a particular branch via
update-scheduled-release-version.ymlon 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. -
Trigger releases for all branches via
release-scheduler.ymlon themainbranch. 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.
Ensure you have no changes in your local repository. Change to a new branch. For example:
$ git checkout -b 5.5.0-RC1-dependenciesReview the rules in build.gradle to ensure the rules make sense. For example, we should not allow major version updates in a patch release. 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. 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.
$ ./gradlew updateDependenciesReview 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.
$ git logIf any of the versions don’t make sense, update build.gradle to ensure that the version is excluded.
Run all the checks:
$ ./gradlew checkIf they don’t work, you can run a git bisect to discover what broke the build. Fix any commits that broke the build.
Check out the original brach:
$ git checkout -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:
-
<github-personal-access-token> - Replace with a 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)
$ ./gradlew updateDependencies -PupdateMode=GITHUB_ISSUE -PgitHubAccessToken=<github-personal-access-token> -PnextVersion=<next-version>Apply any fixes from your previous branch that were necessary.
The following command will check if there are any open issues for the ticket. Before running the command, replace the following values:
-
<github-personal-access-token> - Replace with a 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 title of the milestone you are releasing now (i.e. 5.5.0-RC1)
$ ./gradlew gitHubCheckMilestoneHasNoOpenIssues -PgitHubAccessToken=<github-personal-access-token> -PnextVersion=<next-version>Alternatively, you can manually check using https://github.com/spring-projects/spring-security/milestones
Update the version number in gradle.properties for the release, for example 5.5.0-M1, 5.5.0-RC1, 5.5.0
You will need to update the antora.yml version. If you are unsure of what the values should be, the following task will instruct you what the expected values are:
./gradlew :spring-security-docs:antoraCheckVersionPush the commit and GitHub actions will build and deploy the artifacts If you are pushing to Maven Central, then you can get notified when it’s uploaded by running the following:
$ ./scripts/release/wait-for-done.sh 5.5.0-
Announce via Slack on #spring-release, including the keyword
spring-security-announcingin the message. Something like:
spring-security-announcing 5.5.0 is available.
-
Update
gradle.propertiesversion to nextSNAPSHOTversion, update antora.yml, and then push
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 GitHub personal access token that has a scope of read:org as documented for spring.io api
<next-version> - Replace with the milestone you are releasing now (i.e. 5.5.0-RC1)
<previous-version> - Replace with the previous release which will be removed from the listed versions (i.e. 5.5.0-M3)
$ ./gradlew saganCreateRelease saganDeleteRelease -PgitHubAccessToken=<github-personal-access-token> -PnextVersion=<next-version> -PpreviousVersion=<previous-version>Generate the Release Notes replacing:
-
<next-version> - Replace with the milestone you are releasing now (i.e. 5.5.0-RC1)
$ ./gradlew generateChangelog -PnextVersion=<next-version>
-
Copy the release notes to your clipboard (your mileage may vary with the following command)
cat build/changelog/release-notes.md | xclip -selection clipboard
-
Create the release on GitHub, associate it with the tag, and paste the generated notes
-
In 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.
-
Create a Blog
-
Tweet from [@SpringSecurity](https://twitter.com/springsecurity)