Skip to content

Release management

Intended audience

This guide is intended for maintainers and developers of InvenioRDM itself.

Scope

The guide covers how to release a new version of InvenioRDM.

Overview

We follow semantic versioning. In particular:

  • 0.y.z is for initial development - anything may change at any time.

InvenioRDM consists of:

  • a CLI tool,
  • an instance template,
  • an application, and
  • many modules.

Tool versioning

The Invenio-CLI tool is intended to be able to work with many different application versions, and multiple products (RDM, ILS, ...), and is therefore independently versioned.

Application versioning

The instance template (Cookiecutter-Invenio-RDM) and the application (Invenio-App-RDM) is together considered the application and therefore versioned together.

The application locks each dependent module to their major-level versions so that patches can be distributed without breaking compatibility.

Module versioning

Each module (e.g. Invenio-RDM-Records, Invenio, ...) is versioned independently. Each module MUST follow semantic versioning, so that the application can lock the module version to the major-level release.

Release checklist

Initial iteration

In the beginning of each iteration we start by releasing new development versions of the below modules in the order they specified:

  • flask-resources GitHub (if needed)
  • marshmallow-utils GitHub (if needed)
  • invenio-records-permissions GitHub (if needed)
  • invenio-records-resources GitHub
    • bump flask-resources
    • bump marshmallow-utils
    • bump invenio-records-permissions
  • invenio-users-resources Github
    • bump invenio-administration
    • bump invenio-records-resources
  • invenio-drafts-resources GitHub
    • bump invenio-records-resources
  • invenio-vocabularies GitHub
    • bump invenio-records-resources
  • invenio-requests GitHub
    • bump invenio-records-resources
  • invenio-administration GitHub
    • bump invenio-records-resources
    • bump invenio-vocabularies
  • invenio-communities GitHub
    • bump invenio-administration
    • bump invenio-requests
    • bump invenio-vocabularies
  • invenio-rdm-records GitHub
    • bump invenio-administration
    • bump invenio-drafts-resources
    • bump invenio-vocabularies
    • bump invenio-communities
  • react-invenio-forms GitHub
  • react-invenio-deposit GitHub
    • bump react-invenio-forms
  • invenio-app-rdm GitHub
    • bump invenio-rdm-records
    • bump react-invenio-deposit
    • bump react-invenio-forms
  • cookiecutter-invenio-rdm GitHub
    • bump invenio-app-rdm

For modules in v0.X.Y, the new version is v0.(X+1).0.

For modules in vX.Y.Z, the new version is v(X+1).0.0.dev0.

Pre-release

  • Ensure all dependent modules have been released.
  • Release Invenio-App-RDM (removing the pre-release suffix - e.g. dev0).
  • Cookiecutter-Invenio-RDM:
    • Merge everything to master.
    • Create a new version branch from master using the pattern vX.Y (e.g., if Invenio-App-RDM is v1.0.0, then the branch should be named v1.0).
  • Write release notes in dev branch, check the dev site. Then merge to master@docs-invenio-rdm.

Release

The final step to release the new modules and source code is to release Invenio-CLI. Releasing Invenio-CLI, will make all new installation use the latest released packages.

  • Invenio-CLI:
    • Update Cookiecutter-Invenio-RDM branch version in the source code.
    • Bump version of Invenio-CLI and release.

Post-release

Release a Python or JavaScript package

  • Ensure all PR's are merged in master branch on GitHub.

  • create a PR with commit message "release: vX.Y.Z"

  • the PR contains:

    • a list of changes added to the CHANGES.md file
    • bump version number:
      • python: <package>/__init__.py
      • Javascript: package.json, update package-lock.json

  • create the tag 

    git remote update
git checkout upstream/master
    for the version number see the section about semantic versioning 
    git tag vX.Y.Z
git push upstream vX.Y.Z

Maintenance releases

Maintenance releases follow the same workflow as a new version release. You only need to replace master with maint-x.y branches.

Warning

Be aware that when the independent modules are released, they will be picked up immediately by new InvenioRDM installations. This should not be an issues since the releases MUST be backward compatible.

Trunk based Development Workflow

InvenioRDM follows Trunk-Based Development on the main branch (master) of all its modules. Changes in master usually won't have an out-of-the-box backwards-compatibility assurance. Things might break, but we'll fix them ASAP, since we want to be able to develop reliably.

Stable releases are being maintained under their equivalent maint branches. For example, v12.0.x is maintained on the maint-v12.x branch of invenio-app-rdm. Those releases receive bug fixes following SemVer, e.g., v12.0.1, by backporting (usually via cherry-picking) the fixes from the master branch into the maint branch.

Occasionally, if we see features in master that the community agrees should be in the stable branches, we can organize efforts to backport them using a minor version bump in the stable release (e.g., v12.1.x). To qualify for such minor version bumps, the changes adhere to the following assurances: - The new features MUST be disabled by default using config feature flags - If an instance doesn't enable or use the new features, it MUST still work - If an instance wants to enable or use the new features, there MAY be some migration/upgrade recipes required to be run