Skip to content

Latest commit

 

History

History
121 lines (95 loc) · 4.42 KB

RELEASING.md

File metadata and controls

121 lines (95 loc) · 4.42 KB

Release process for Nickel

You're ready to release a new version of Nickel - congrats!

This document explains how to do so step by step while keeping the various crates and dependent repositories (such as the website) in a consistent state.

Steps to make a release

Prepare

  1. Branch out from master to a dedicated branch X.Y.Z-release: git checkout -b X.Y.Z-release

  2. Bump the version number of all the crates of the workspace to X.Y.Z:

    • Bump the version attribute to X.Y.Z in files ./Cargo.toml, ./utilities/Cargo.toml, lsp/nls/Cargo.toml and ./nickel-wasm-repl/Cargo.toml.

    • Bump the version of the interdependencies of the above crates. For example, nickel-lang has the following line in ./Cargo.toml under [dev-dependencies]:

      nickel-lang-utilities = {path = "utilities", version = "0.3.0"}

      You have to bump the version number to X.Y.Z of such dependencies on nickel-lang, nickel-lang-utilities, or any other crate of the workspace as well.

    Commit and push your changes.

  3. Make sure that everything builds: run nix flake check at the root of the repository.

  4. Add the changelog since the last release in RELEASES.md. GitHub is able to automatically generate release notes: refer to this guide. While the output needs to be reworked, it's a useful starting point. Commit and push your changes.

  5. Set the stable branch to point to your new X.Y.Z-release. Because the stable branch usually contains specific fixes, or cherry-picked commits, we'll have to force push. We advise to first save the previous state in a local branch:

    git checkout stable
git branch stable-local-save

    If anything goes wrong, you can reset stable to its previous state:

    git checkout stable
git reset --hard stable-local-save
git push --force-with-lease

    Update the stable branch:

    git checkout stable
git reset --hard X.Y.Z-release`
git push --force-with-lease

Release on crates.io

  1. Remove references to nickel-lang-utilities from the [dev-dependencies] sections of the crates to be published: ./Cargo.toml for nickel-lang and ./lsp/nls/Cargo.toml for nickel-lang-lsp (work-around for cargo:#4242.

    Commit those changes temporarily to please cargo, but they will be dropped later. Do not push.

  2. Check that cargo publish --dry-run succeeds. For this to work, you will need to be signed in to crates.io with a GitHub account that is part of the Nickel Core team, and have a crates.io API key saved locally on your machine (normally via cargo login). For help with this, contact the Nickel maintainers.

  3. Release on crates.io: cargo publish

  4. Ditch the potential changes made to the cargo manifests at step 1. by dropping the corresponding commit.

Release on GitHub

  1. Build the docker image and copy the output somewhere:

    nix build .#dockerImage
cp ./result nickel-X.Y.Z-docker-image.tar.gz

  2. Do the release on GitHub, and include the docker image built in 1. Please look at previous releases for the naming convention of git tags.

Redeploy nickel-lang.org with the new release

  1. Checkout the nickel-lang repository.

  2. Branch out from master and update the Nickel input:

    git checkout -b release/X.Y.Z
nix flake lock --update-input nickel
git add flake.lock
git commit -m "Update to Nickel vX.Y.Z"
git push -u origin @

    Open a pull request on the nickel-lang repository. Once the CI is green and the PR is merged, nickel-lang.org will be automatically redeployed with the new version of Nickel used for the playground and the documentation.

Port changes to master

  1. Cherry-pick the following commits into separate PRs to master:
    • Bumping the version numbers done in Preparation 2.
    • Updating release notes done in Preparation 5.
    • Fixes that you made locally for nix flake check, cargo doc or any other command.
  2. Profit!