Hare release policy

Hare ships quarterly releases as we work towards Hare 1.0. Releases use the versioning scheme 0.YY.Q, where YY is the two-digit release year and Q is the quarter number (from zero); so the release in Q1 2024 is 0.24.0.

The Hare toolchain’s chief dependency is qbe. Each Hare version is pinned to a specific qbe release, which is documented in the release notes corresponding to that Hare version.

The current release manager is Drew DeVault.

Breaking changes

Breaking changes to the compiler, the standard library or user facing commands which are included in each release are documented in the release notes. Commits introducing breaking changes must include a Breaking-Change: message trailer, listing the components that are affected. Authors of such changes are also strongly encouraged to include a detailed summary of the breaking change.

The release manager will collect breaking changes and summarize them in the release notes for affected versions, providing instructions for affected users to update their code. If possible, an automated migration procedure will be prepared on a best-effort basis.

Examples

When making changes to one or more modules’ public interfaces, list the affected modules, suffixing each with ::. Do not list modules that had to be modified as a result of this breaking change but whose own public API was not modified. If the commit modifies the part of rt:: that is used as the language runtime, list abi as one of the modified components.

strings: rename pad functions per convention

The following functions in strings:: have been renamed:

* strings::padstart renamed to strings::lpad
* strings::padend renamed to strings::rpad

Breaking-Change: strings::

When modifying commands in a user facing way, list affected commands, referring to them as if writing a man page:

build driver: drop -x flags to deps and build

It caused problems and was rarely used. Use -y -z instead.

Breaking-Change: hare-deps(1), hare-build(1)

When making backwards incompatible changes to the compiler, list one or more of the following:

  • abi- for modifications to the compiler’s interface to the language runtime

  • language- for modifications to syntax, typechecking rules or runtime behavior

handle allocation failure by returning nomem

previously, if the result type of an allocation-expression was not a
nullable pointer type, the builtin would abort. this is now handled
by instead returning nomem.

this commit introduces the following breaking changes:

        - nomem cannot be used as a name anymore
        - alloc, insert and append have different return values now
        - harec binary interface has changed.

Breaking-Change: language, abi

Release process

One or two weeks prior to the start of each financial quarter, the release manager will prepare a release branch named “v0.YY.Q” cut from the latest master branch, and tag 0.YY.Q-rc1 from this branch, notifying hare-dev with a preliminary changelog.

Each week following rc1, the release manager will make a judgement call on the release’s quality based on feedback from the community; if the release is not ready then any additional bugfixes will be cherry-picked from master and rcN+1 tagged. If the release is determiend to be ready, 0.YY.Q is tagged and the release notes are posted to hare-announce.

Extended library

The extended library will ship tagged releases which track Hare releases. However, the extended library does not necessarily change often; in a given quarter most extended libraries will not have received any patches. As such, new releases for the extlib are only tagged upon request, or if necessity demands (such as when updated to address a breaking change).

Release checklist

  1. Cut X.YY.Q branch

  2. Update scripts/version, commit

  3. Tag release candidate with changelog (git shortlog)

For each subsequent release (rc or final):

  1. Update scripts/version, commit

  2. Tag with changelog (git shortlog)