Add an issue Crystal release X.Y.Z
in https://github.com/crystal-lang/distribution-scripts/issues with a copy of this document. In this way it's easy to track the progress of the release (Helper: scripts/prepare-crystal-release.sh
)
- (minor) Announce expected release date and time span for feature freeze
- (minor) Feature freeze is about two weeks before release
- (minor) Set date on milestone
- Prepare the changelog entry:
crystal:scripts/github-changelog.cr
- Ensure that all merged PRs are added to the milestone (check
is:pr is:merged sort:updated-desc no:milestone
). - Ensure that all milestoned PRs are properly labelled (check
is:pr is:merged sort:updated-desc no:label milestone:${VERSION}
).
- Ensure that all merged PRs are added to the milestone (check
- Start preparing release notes
- (minor) Start feature freeze period
- (minor) Either no merging of features into
master
or split off release branch for backporting bugfixes.
- (minor) Either no merging of features into
- Publish release PR draft
- (minor) It should contain the expected date of the release.
- It should be populated with updates to
CHANGELOG.md
,src/VERSION
and the version inshard.yml
.
- (minor) Ensure documentation for language and compiler changes and other relevant changes is up to date.
- (minor) Crystal Book
- (minor) Update language specification
- (minor) Update compiler manual
- (minor) Add or update guides / tutorials?
- (minor) Crystal Book
- Ensure that test-ecosystem functions and succeeeds on master
- Finalize the release PR
- Make sure all changes are mentioned in the changelog
- Check release date
- Un-draft the PR
- (minor) Split off release branch (
release/x.y
) - Verify Maintenance CI workflow succeeds on the HEAD of the release branch
- Smoke test with test-ecosystem
- Run Test Crystal & Shards Workflow with the release branch as
crystal_branch
.
- Run Test Crystal & Shards Workflow with the release branch as
- Merge the release PR
- Make the release and publish it on GitHub:
../distribution-scripts/processes/scripts/make-crystal-release.sh
(run fromcrystallang/crystal@$VERSION
work tree). This performs these steps:- Tag & annotate the commit with the changelog using
<M.m.p>
pattern as version
git tag -s -a -m $VERSION $VERSION
git push --tags
- Publish Github release (https://github.com/crystal-lang/crystal/releases/new)
- Copy the changelog section as description
- Binaries are added later
- Tag & annotate the commit with the changelog using
- Close milestone (https://github.com/crystal-lang/crystal/milestones)
- Wait for the release build in circle CI (https://app.circleci.com/pipelines/github/crystal-lang/crystal)
- Publish build artifacts from CircleCI and GitHub Actions to GitHub release. For
URL_TO_CIRCLECI_ARTIFACT
grab the URL of any of the build artifacts in circleCI (doesn't matter which).- Upload build artifacts from CircleCI:
../distribution-scripts/processes/scripts/publish-crystal-packages-on-github.sh $URL_TO_CIRCLECI_ARTIFACT
(run fromcrystallang/crystal@$VERSION
work tree)crystal-*-darwin-*.tar.gz
crystal-*-linux-*.tar.gz
crystal-*.pkg
crystal-*-docs.tar.gz
- Upload build artifacts from GHA (Windows):
crystal-release.zip
->crystal-$VERSION-windows-x86_64-msvc-unsupported.zip
crystal-installer.zip
-> unzip ->crystal-$VERSION-windows-x86_64-msvc-unsupported.exe
- Upload build artifacts from CircleCI:
- Push changes to OBS for building linux packages
- Checkout https://github.com/crystal-lang/distribution-scripts and go to
./packages
- Configure build.opensuse.org credentials in environment variables:
export OBS_USER=
export OBS_PASSWORD=
- (minor) Update the
crystal
package:./obs-release.sh devel:languages:crystal crystal $VERSION
- (minor) Uses the docker image
crystallang/osc
to run the CLI client for OBS. - (minor) The script creates a branch in you home project, updates the version and pushes it back to OBS.
- (minor) You can also run the commands from that file manually and check build locally with
- (minor)
osc build xUbuntu_20.04 x86_64
- (minor)
osc build Fedora_Rawhide x86_64
- (minor)
- (minor) Uses the docker image
- (minor) Create the
crystal${VERSION%.*}
package:./obs-new-minor.sh devel:languages:crystal crystal${VERSION%.*} $VERSION crystal${OLD_VERSION%.*}
- (patch) Update the
crystal${VERSION%.*}
package:./obs-release.sh devel:languages:crystal crystal${VERSION%.*} $VERSION
- Now OBS builds the packages. It’s best to follow the build status in the browser:
open https://build.opensuse.org/project/show/home:$OBS_USER:branches:devel:langauges:crystal/crystal
- Wait for all package build jobs to finish and succeed
- When everything is green, create a submit request against the original packages (Submit package link in the menu bar on the package in your branch)
- Verify package installation
OBS_PROJECT=devel:languages:crystal bats test
- Checkout https://github.com/crystal-lang/distribution-scripts and go to
- Tag
latest
docker images- Versioned docker images have been pushed to dockerhub.
- Now just assign the
latest
tags: ./docker/apply-latest-tags.sh ${VERSION}
- Publish snap package (you can use the docker image
snapcore/snapcraft
for running the following commands)docker run --pull=always --rm -it snapcore/snapcraft
- You need to logged in via
snapcraft login
- Recent tagged release is published directly to edge channel. The CI logs the snap revision number. Otherwise the .snap file is in the artifacts.
- Check the current status to find the revision of the tagged release otherwise:
snapcraft status crystal
snapcraft release crystal <revision-number> beta
snapcraft release crystal <revision-number> stable
- Check PR for homebrew: https://github.com/Homebrew/homebrew-core/pulls?q=is%3Apr+crystal+sort%3Aupdated-desc
- It should've been automatically created
- Publish API docs
- Have
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
env variables defined- Keys can be generated at https://console.aws.amazon.com/iam/home#/security_credentials (contact a Manas admin if you don't have access).
- Run
make -C docs publish_docs dist-redirect_latest CRYSTAL_VERSION=${VERSION}
to publish docs toapi/${VERSION}
and apply redirect fromapi/latest
toapi/${VERSION}
- Have
- (minor) Publish Crystal book
- (minor) Create
release/${VERSION%.*}
branch and push it tocrystal-lang/crystal-book
(deployment happens automatically in GHA) - (minor) Verify that deployment was successfull
- (minor) Create
- Publish release notes on the website
- Post announcement in https://forum.crystal-lang.org/c/news/official
- Announce on social media accounts (via Buffer; credentials are in Passbolt) and pin release posts
- Update https://github.com/crystal-lang/crystal-book/blob/master/crystal-version.txt
- (minor) Post the release in https://opencollective.com/crystal-lang
- Update crystal
master
branch to use released version:crystal:scripts/release-update.sh ${VERSION}
- Edit PREVIOUS_CRYSTAL_BASE_URL in
.circleci/config.yml
- Edit DOCKER_TEST_PREFIX in
bin/ci
- Edit
prepare_build
on_osx download package and folder - Edit
.github/workflows/*.yml
to point to docker image - Edit
shell.nix
latestCrystalBinary
usingnix-prefetch-url --unpack <url>
- Edit PREVIOUS_CRYSTAL_BASE_URL in
- (minor) Increment
src/VERSION
and version inshard.yml
to the next minor plus-dev
suffix - (minor) Perform uncomment/todos left in the repo
- Update default base version in test-ecosystem:
test-ecosystem:scripts/release-update.sh ${VERSION}
- Merge
release/${VERSION%.*}
branch intomaster
(if the two have diverged)
- This needs to be a merge commit. Those are disabled in the GitHub UI.
git switch master && git pull && git merge release/${VERSION%.*}; git checkout master src/VERSION && git add src/VERSION && git commit
- Double check merge commit history is as expected
git push
(GitHub branch protection rules normally prevent direct pushes tomaster
. This needs to be deactivated for this purpose, which can be on a per-user basis.)