Release Crystal 1.16.0

[straight-shoota]

Release preparation

1. Announce expected release date (2025-04-09) and time span for feature freeze (starting on 2025-03-26)
   • Feature freeze is about two weeks before release
   • Set date on milestone
2. Prepare the changelog entry: crystal:scripts/github-changelog.cr Changelog for 1.16.0 crystal#15602
   • 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:1.16.0).
3. Start preparing release notes Release notes 1.16.0 crystal-website#910
4. Start feature freeze period (on 2025-03-26)
   • Either no merging of features into master or split off release branch for backporting bugfixes.
5. Publish release PR draft
   • It should contain the expected date of the release.
   • It should be populated with updates to CHANGELOG.md, src/VERSION and the version in shard.yml.
6. Ensure documentation for language and compiler changes and other relevant changes is up to date.
   • Crystal Book
     • Update language specification
       • macro sizeof and alignof Document macro versions of sizeof and alignof crystal-book#823
     • Update compiler manual
       • --output Update documentation for --output option crystal-book#818
       • CRYSTAL_EXEC_PATH Document environment variable CRYSTAL_EXEC_PATH [followup #15186] crystal#15631 Document CRYSTAL_EXEC_PATH crystal-book#822
       • LLVM 20 Bump support for LLVM 20 crystal-book#819
     • Add or update guides / tutorials?
       • :showdoc: Add documentation for :showdoc: crystal-book#824
7. Look for library updates, check and document compatibility at https://crystal-lang.org/reference/man/required_libraries.html and in lib bindings
8. Ensure that test-ecosystem functions and succeeds on master
   • Run Test Crystal & Shards Workflow

Release process (on 2025-04-09)

Source release

1. Finalize the release PR
   • Make sure all changes are mentioned in the changelog
   • Check release date
   • Un-draft the PR
2. Split off release branch (release/x.y)
3. Verify Maintenance CI workflow succeeds on the HEAD of the release branch
4. Smoke test with test-ecosystem
   • Run Test Crystal & Shards Workflow with the release branch as crystal_branch.
5. Merge the release PR
6. Make the release and publish it on GitHub: ../distribution-scripts/processes/scripts/make-crystal-release.sh (run from crystallang/crystal@1.16.0 work tree). This performs these steps:
   1. Tag & annotate the commit with the changelog using <M.m.p> pattern as version
   • git tag -s -a -m 1.16.0 1.16.0
   • git push --tags
   2. Publish Github release (https://github.com/crystal-lang/crystal/releases/new)
      • Copy the changelog section as description
      • Binaries are added later
7. Close milestone (https://github.com/crystal-lang/crystal/milestones)
8. Wait for the release build in circle CI (https://app.circleci.com/pipelines/github/crystal-lang/crystal)

Binary releases

3. 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 from crystallang/crystal@1.16.0 work tree)
     • crystal-*-darwin-*.tar.gz
     • crystal-*-linux-*.tar.gz
     • crystal-*.pkg
     • crystal-*-docs.tar.gz
   • Upload build artifacts from GHA (Windows):
     • Windows CI: crystal-release.zip -> crystal-1.16.0-windows-x86_64-msvc-unsupported.zip
     • Windows CI: crystal-installer.zip -> unzip -> crystal-1.16.0-windows-x86_64-msvc-unsupported.exe
     • MinGW-w64 CI: x86_64-mingw-w64-crystal.zip -> crystal-1.16.0-windows-x86_64-gnu-unsupported.zip
4. Push changes to OBS for building linux packages
   1. Checkout https://github.com/crystal-lang/distribution-scripts and go to ./packages
   2. Configure build.opensuse.org credentials in environment variables:
      • export OBS_USER=
      • export OBS_PASSWORD=
   3. Update the crystal package: ./obs-release.sh devel:languages:crystal crystal 1.16.0
      • Uses the docker image crystallang/osc to run the CLI client for OBS.
      • The script creates a branch in you home project, updates the version and pushes it back to OBS.
      • You can also run the commands from that file manually and check build locally with
        • osc build xUbuntu_20.04 x86_64
        • osc build Fedora_Rawhide x86_64
   4. Create the crystal1.16 package: ./obs-new-minor.sh devel:languages:crystal crystal1.16 1.16.0 crystal${OLD_VERSION%.*}
   5. Now OBS builds the packages. It’s best to follow the build status in the browser:
      1. open https://build.opensuse.org/project/show/home:$OBS_USER:branches:devel:langauges:crystal/crystal
      2. Wait for all package build jobs to finish and succeed
   6. 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)
   7. Verify package installation
      • OBS_PROJECT=devel:languages:crystal bats test
5. Tag latest docker images
   • Versioned docker images have been pushed to dockerhub.
   • Now just assign the latest tags:
   • ./docker/apply-latest-tags.sh 1.16.0
6. Publish snap package
   • On https://snapcraft.io/crystal/releases promote the latest/edge release to latest/beta and then latest/stable
7. 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 documentation for the release

1. Publish API docs
   1. Have AWS_ACCESS_KEY_ID and AWS_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).
   2. Run make -C docs publish_docs dist-redirect_latest CRYSTAL_VERSION=1.16.0 to publish docs to api/1.16.0 and apply redirect from api/latest to api/1.16.0
2. Publish Crystal book
   1. Create release/1.16 branch and push it to crystal-lang/crystal-book (deployment happens automatically in GHA)
   2. Verify that deployment was successfull

Release announcements

1. Publish release notes on the website
2. Post announcement in https://forum.crystal-lang.org/c/news/official
3. Announce on social media accounts (via Buffer; credentials are in Passbolt) and pin release posts
4. Update https://github.com/crystal-lang/crystal-book/blob/master/crystal-version.txt
5. Post the release in https://opencollective.com/crystal-lang

Post-release

1. Update crystal master branch to use released version: crystal:scripts/release-update.sh 1.16.0 Update previous Crystal release 1.16.1 crystal#15649
   • 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 using nix-prefetch-url --unpack <url>
2. Increment src/VERSION and version in shard.yml to the next minor plus -dev suffix
3. Perform uncomment/todos left in the repo
4. Update default base version in test-ecosystem: test-ecosystem:scripts/release-update.sh 1.16.0
5. Merge release/1.16 branch into master (if the two have diverged)

• This needs to be a merge commit. Those are disabled in the GitHub UI.
• Create branch and PR:

  git fetch upstream release/1.16 master
  git switch -c merge/1.16.0 upstream/master
  git merge upstream/release/1.16
  # resolve conflicts
  git commit -m 'Merge `release/1.16` into master'
  git log --graph --decorate --pretty=oneline --abbrev-commit
  git push -u upstream merge/1.16.0
  gh pr create --title 'Merge `release/1.16` into master' --label 'topic:infrastructure'

• Merge PR locally:

  git switch master
  git merge --ff-only merge/1.16.0
  # double check history
  git log --graph --decorate --pretty=oneline --abbrev-commit
  git push

• GitHub branch protection rules normally prevent direct pushes to
  master. This needs to be deactivated for this purpose, which can be on a
  per-user basis.
• In case master has diverged, --ff-only merge will fail. Then you can
  first rebase merge/1.16.0 on current master with git rebase master --rebase-merges.