Versioning Your Extension

If you have an ambitious project or a large team working on your extensions, you may have wondered about version control.

Versioning helps ensure customers get the right code, and helps inform team members about code changes they did not personally contribute to.

We strongly recommend a changelog system to make deploying and maintaining your code safer and easier, and we’ve created some tools to make this process simple.

When you’ve made your changes and are ready to submit, the last step is to run q2 changelog.

q2 changelog is a repository level tool: it will first prompt you to select an extension or create a changelog for the repository as a whole.

Once you’ve chosen the project to create a changelog for, the tool will prompt you to choose a version type: major, minor, or patch. This tool uses a three digit strategy called Semantic Versioning, which is how we version the Caliper SDK itself.

Under this system, these categories have the following meanings:

  • Major is for any backwards incompatible changes

  • Minor is for backwards compatible new features or major feature changes

  • Patch is for backwards compatible bug fixes or minor changes

So version ‘1.5.7’ would have a major version of 1, a minor version of 5, and a patch version of 7.

Once you’ve chosen your version type, the tool will prompt you to compose the changelog itself. Here again we use an established pattern, spelled out at Keep a Changelog.

The tool will ask you to select one of six categories:

  • Added for new features

  • Changed for changes in existing functionality

  • Deprecated for soon-to-be removed features

  • Removed for now removed features

  • Fixed for any bug fixes

  • Security in case of vulnerabilities

Once you select a category, just type a summary of your change right into the prompt and it will be saved for later. The tool will then prompt you for your next change.

When you have documented all your changes, select ‘Complete’. Your changelog will be generated, or automatically updated if a changelog already exists.

Note

You can read or fetch the changelog for a running repository with the /changelog endpoint. After you generate a changelog, view it by navigating to {the URL serving your extension}/changelog in a browser or fetch it at the command line with a tool like curl.