Release Crystal 1.18.0

[straight-shoota]

Release preparation

1. Announce expected release date (2025-10-14) and time span for feature freeze (starting on 2025-09-30)
   • 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.18.0 crystal#16153)
   • 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.18.0).
3. Start preparing release notes
4. Start feature freeze period (on 2025-09-30)
   • Either no merging of features into master or split off release branch for backporting bugfixes.
5. Publish release PR draft (Release 1.18.0 crystal-website#985)
   • 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
       • Add Deprecated annotation in Built-in annotations: Add Deprecated built-in annotation crystal-book#842
       • Fresh variable naming scheme from Group temporary variables by file name: compound array assignments crystal#16122 (Not necessary because the example uses an unnamed file where variables are not prefixed with a hash of the file name)
     • Update compiler manual
       • CRYSTAL_DUMP_TYPE_INFO from Add the ability to dump type information to a JSON file crystal#16027
     • Add or update guides / tutorials?
   • API Docs
     • ExecutionContext: default context, description of Concurrent, #resize: Tweak docs for Fiber::ExecutionContext crystal#16196
     • Deprecated: parameters, enhance examples: Enhance documentation of Deprecated annotation crystal#16195
7. Look for library updates, check and document compatibility at https://crystal-lang.org/reference/man/required_libraries.html and in lib bindings
   • LLVM update 21.0->21.1/22.0: Update supported LLVM version to include 22.0 crystal-book#844
8. Ensure that test-ecosystem functions and succeeds on master
   • Run Test Crystal & Shards Workflow

Release process (on 2025-10-14)

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.18.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.18.0 1.18.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)
9. Fast-forward release/1.18 to master@1.18.0

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.18.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.18.0-windows-x86_64-msvc-unsupported.zip
     • Windows CI: crystal-installer.zip -> unzip -> crystal-1.18.0-windows-x86_64-msvc-unsupported.exe
     • MinGW-w64 CI: x86_64-mingw-w64-crystal.zip -> crystal-1.18.0-windows-x86_64-gnu-unsupported.zip
     • MinGW-w64 CI: aarch64-mingw-w64-crystal.zip -> crystal-1.18.0-windows-aarch64-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.18.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.18 package: ./obs-new-minor.sh devel:languages:crystal crystal1.18 1.18.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.18.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.18.0 to publish docs to api/1.18.0 and apply redirect from api/latest to api/1.18.0
   3. Update API docs' 404 page to add <base href="/api/${VERSION}/" /> in the <head>
2. Publish Crystal book
   1. Create release/1.18 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
   • Make sure all links to API docs point to /api/1.18.0/
   • Insert number of changes and contributers
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.18.0
   • 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>
   • Increment src/VERSION and version in shard.yml to the next minor plus -dev suffix
2. Perform uncomment/todos left in the repo
3. Update default base version in test-ecosystem: test-ecosystem:scripts/release-update.sh 1.18.0
4. Merge release/1.18 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.18 master
  git switch -c merge/1.18.0 upstream/master
  git merge upstream/release/1.18
  # resolve conflicts
  git commit -m 'Merge `release/1.18` into master'
  git log --graph --decorate --pretty=oneline --abbrev-commit
  git push -u upstream merge/1.18.0
  gh pr create --title 'Merge `release/1.18` into master' --label 'topic:infrastructure'

• Merge PR locally:

  git switch master
  git merge --ff-only merge/1.18.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.18.0 on current master with git rebase master --rebase-merges.

[matiasgarciaisaia]

I tried adding the change from #370, and I think the Github editor and I broke all the formatting after that line 🤦

[straight-shoota]

It looks good to me...

[ysbaddaden]

(I updated the dates)