Release Crystal 1.19.0

[ysbaddaden]

Release preparation

1. Announce expected release date (2026-01-14) and time span for feature freeze (starting on 2025-12-31)
   • Feature freeze is about two weeks before release
   • https://forum.crystal-lang.org/t/upcoming-1-19-release/8598
2. Set date on the milestone
3. Prepare the changelog entry: (crystal) scripts/update-changelog.cr 1.19.0 from the HEAD of the release branch (or master)
   • 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.19.0).
   • Ensure the milestone has Due date set.
4. Start preparing release notes, publish draft in crystal-lang/crystal-website (summary of changes that are most relevant for users)
5. Start feature freeze period (on 2025-12-31)
   • Either no merging of features into master or split off release branch for backporting bugfixes.
6. 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.
7. Ensure documentation for language and compiler changes and other relevant changes is up to date.
   • Crystal Book
     • Update language specification
     • Update compiler manual
     • Add or update guides / tutorials?
8. Look for library updates, check and document compatibility at https://crystal-lang.org/reference/man/required_libraries.html and in lib bindings
9. Ensure that test-ecosystem functions and succeeds on master
   • Run CI Workflow on master (uses nightly build)

Release process (on 2026-01-14)

Source release

1. Finalize the changelog PR
   • Make sure all changes are mentioned in the changelog
   • Check release date
   • Un-draft the PR
2. Split off release branch release/1.19 from master to trigger Maintenance CI
3. Verify Maintenance CI workflow succeeds on the HEAD of the release
   branch: https://app.circleci.com/pipelines/github/crystal-lang/crystal?branch=release%2F1.19
4. Smoke test with test-ecosystem
   • Run CI Workflow with crystal=branch:release/{VERSION%.*}.
5. Merge the changelog PR
6. Make the release and publish it on GitHub: (crystal) ../distribution-scripts/processes/scripts/make-crystal-release.sh (run from crystallang/crystal@1.19.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.19.0 1.19.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.19 to master@1.19.0

Binary releases

1. 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: (crystal) ../distribution-scripts/processes/scripts/publish-crystal-packages-on-github.sh $URL_TO_CIRCLECI_ARTIFACT (run from crystallang/crystal@1.19.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.zip -> crystal-1.19.0-windows-x86_64-msvc-unsupported.zip
     • Windows CI: crystal-installer.zip -> unzip -> crystal-1.19.0-windows-x86_64-msvc-unsupported.exe
     • MinGW-w64 CI: x86_64-mingw-w64-crystal.zip -> crystal-1.19.0-windows-x86_64-gnu-unsupported.zip
     • MinGW-w64 CI: aarch64-mingw-w64-crystal.zip -> crystal-1.19.0-windows-aarch64-gnu-unsupported.zip
2. Publish the GitHub release
3. 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: (distribution-scripts) ./obs-release.sh devel:languages:crystal crystal 1.19.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.19 package: (distribution-scripts) ./obs-new-minor.sh devel:languages:crystal crystal1.19 1.19.0 crystal1.18
   5. Now OBS builds the packages. It’s best to follow the build status in the browser:
      1. open https://build.opensuse.org/package/show/home:$OBS_USER:branches:devel:languages:crystal/crystal
      2. open https://build.opensuse.org/package/show/home:$OBS_USER:branches:devel:languages:crystal/crystal1.19
      3. 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 page actions (left sidebar) in your branch.
   7. (optional) Verify package installation
      • (distribution-scripts/packages) OBS_PROJECT=devel:languages:crystal bats test
4. Tag latest docker images
   • Versioned docker images have been pushed to Docker Hub.
   • Now just assign the latest tags:
   • (distribution-scripts) ./docker/apply-latest-tags.sh 1.19.0
5. Publish snap package
   • On https://snapcraft.io/crystal/releases promote the latest/edge release to latest/beta and then latest/stable
6. 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 (distribution-scripts) make -C docs publish_docs release_latest_docs CRYSTAL_VERSION=1.19.0 to publish docs to api/1.19.0, apply redirect from api/latest to api/1.19.0 and set the 404 error page
   3. Update API docs' 404 page to add <base href="/api/1.19.0/" /> in the <head>
2. Publish Crystal book
   1. Make sure release/1.18 branch is merged into master (if not, create a PR; it needs to be merged as a merge commit)
   2. Create release/1.19 branch and push it to crystal-lang/crystal-book (deployment happens automatically in GHA)
   3. Verify that deployment was successful

Release announcements

1. Publish release notes on the website
   • Make sure all links to API docs point to /api/1.19.0/
   • Insert number of changes and contributers
2. Wait for website to build, then visit the release notes page. This should
   create a thread for comments on the forum. Publish that topic
   ("List topic" in the wrench icon) and add tag release.
3. Announce on social media accounts (via Buffer; credentials are in Passbolt) and pin release posts
4. Have the project manager post the release in https://opencollective.com/crystal-lang

Post-release

1. Create a pull request to update master branch to use released version:
   (crystal) scripts/release-update.sh 1.19.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>
   • Branch: infra/release-update. Commit message: Update previous Crystal release 1.19.0
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. Merge release/1.19 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.19 master
     git switch -c merge/1.19.0 upstream/master
     git merge upstream/release/1.19
     # resolve conflicts
     git commit -m \'Merge `release/1.19` into master\'
     git log --graph --decorate --pretty=oneline --abbrev-commit
     git push -u upstream merge/1.19.0
     gh pr create --title \'Merge `release/1.19`@`%{VERSION} into `master`\' --label \'topic:infrastructure\'

   • Merge PR locally:

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