Creating Tags and Releases

To create a new Release, you have to first create a Tag. This page explains how to do this.

Note: For the CQL repo, there is no Release Notes.md in the repo yet. Instead, this can be added at the step where the Release is created mentioned later on this page.

Before You Start

• Before you start, ensure all PR's are merged to the current development branch (develop-2.0 at the time of writing this page)
• Capture the Firely .NET SDK version used in the VONK CQL Plugin. These need to be in sync
• You will need permissions to create Tags and Releases

Update Version

To update the version in the .NET assemblies follow these steps. Refer to this example issue 478 and PR 482 which upgrades to 2.0.2-alpha.

1. Start by creating an issue on the backlog.

2. Check out the latest repo and create a branch

3. Open all the *.props files, and update the VersionPrefix and VersionSuffix properties.

   Semantic Versioning Guideline:

   Update VersionPrefix:

   • MAJOR when you make incompatible API changes
   • MINOR when you add functionality in a backward compatible manner
   • PATCH when you make backward compatible bug fixes

   Update VersionSuffix:

   • alpha is an exploratory phase and subject to changes without notice, usually for internal use during early testing
   • beta is when features are locked down and features being developed, targeted for general public during external testing
   • rc (release candidate) is when features are completed and stable, for final testing before a official release
   • <leave blank> (official release) is when there are no major bugs left and reliable enough for public use

4. Important - Keep the version in sync between the Firely SDK used and that in the VONK CQL Plugin. In the .props files, also update FirelySdkVersion if necessary.

5. You have to rebuild the entire solution, which includes the demo projects. This will also update the [System.CodeDom.Compiler.GeneratedCode(".NET Code Generation", "2.0.2.0")] attribute version in the C# generated code.

6. Commit the branch and pull and merge it. Important: You cannot deploy Releases from a Pull Request itself.

Tagging

The next step is to tag a commit with a version number. After completing the steps above, continue as follows:

1. Find the commit version that you want the new release on.

2. On your local environment open a command prompt in your folder containing the repo, then run these commands (replace the {tags}):

   1. Optional: To check the current list of tags in the repo

   git tag --list 

   1. Make sure you're on the main branch or your repo with the latest commit. Then capture the commit ID for the next step

   git rev-parse HEAD

   1. Create a new tag for a specific commit id, and with an optional message

   git tag -a v2.0.2-alpha {commit-id}  -m "{message here}"

   1. Push the new tag to the remote repo. You will need permissions for this.

   git push origin v2.0.2-alpha

Releasing

After pushing the new tag from above, manually create a release for it:

1. In GitHub, go to Tags, click ... on the tag you're interested to release and click Create Release

2. Click the Generate Release Notes button, and add additional comments as necessary

3. For Pre-Release releases, tick the checkbox for Pre-release

4. Wait for pipeline to build

5. Click Approve on the last Deploy packages to Nuget step

6. A few minutes may pass before the Nuget package is visible.

References

• Creating Releases for firely-net-sdk, which is a useful guide to a more complete process, and includes steps for adding manual release notes.