Creating a Version 1.x Release

WARNING THIS PAGE IS CURRENTLY UNDER CONSTRUCTION.

Because we use the main branch for version 2.x development, new releases of the TestCentric 1.x GUI use the v1-build branch. All feature branches intended for release in the 1.x series are created from v1-build and are eventually merged back to that branch.

This page describes how we create a new 1.x release of the TestCentric GUI starting at the point where all issues to be included in the release have been closed and merged to v1-build. The current code in v1-build serves as the basis for the release.

Required Permissions

UNDER CONSTRUCTION

Milestone

In order to begin the release process, there should already be a milestone named for the release, like 1.7.0. The milestone name is required to be the same as the release package version, with three components. Our scripts depend on this.

All closed and merged issues to be included in the release must be part of the milestone. Any remaining open issues should be transferred to the next milestone before beginning this process, since the milestone will eventually be closed by the script.

The milestone description will appear in the release that is created on GitHub. You should edit it to describe the release in general. Start the description with a blank line to separate it from generated text that will precede it in the release notes.

NOTE: This process does not yet support pre-releases, like 1.5.0-beta2. Such releases would have to be done manually.

Release Branch Creation

We use a release branch to isolate the process of creating the release from more substantive changes like bug fixes and new features. Ideally, you should leave the v1-build branch unchanged from the time the release branch is created until the new release is published in order to avoid a merge conflict later in the process. This is generally not a problem because the release process takes very little time.

1. Create a new local branch named "release-{milestone}", like release-1.7.0.

2. Make any changes needed for the release, add and commit them. Normally, no changes are needed. Any change of significance should have been done in a PR before starting the process.

3. Commit your changes and push the new branch, for example: git push -u origin release-1.7.0. An AppVeyor build is triggered. In case of failure, fix and repeat until it is successful.

4. The AppVeyor build creates a draft release on GitHub. Check it to see that all closed issues appear and that the text is correct. No assets have been added to the draft release at this point.

5. Immediately edit the draft release online so it will create the release label on the v1-build branch rather than the default main branch.

6. If necessary, repeat steps 2 through 5 on the release branch until everything is correct.

NOTE: If you update the milestone but don't make any local changes, you don't need to do a new push. Instead, use the AppVeyor menu option to re-run the same commit.

7. As a final step before merging the release branch into v1-branch, you may edit the draft release text in any way you like. This is useful only if you want something to appear in the release notes but not in the milestone.

Production Release

8. Create a PR for the release branch. Change the target for the merge from main to v1-build before saving it.

9. Wait for the CI build to complete successfully and then merge it. This will trigger a new build and produce a dev release on MyGet. The v1-build branch now has all the changes from the release branch.

10. Go to the draft release on GitHub and click Publish. This will tag the release on v1-build and trigger a final production build.

11. The production build uploads all packages to NuGet and Chocolatey and adds them as assets on the GitHub release. The milestone is closed and all the issues have comments added indicating the release in which they were resolved.

12. Update the Release Notes on the website.

13. Notify users of the new release.

Recovery from Publishing Errors

Prior to publishing the release, errors are handled in the normal way. Changes may be made to the local branch and pushed until the errors are corrected. Errors in the publishing step require special handling because publishing affects multiple external sites.

The build triggered by clicking the Publish button in GitHub runs the usual Build, Test and Package steps first. These should not cause any errors since the code is unchanged from earlier builds.

Next the build publishes packages to MyGet, NuGet and Chocolatey and creates the Production release on GitHub. Generally, errors can occur at any of these steps, usually due to security or network problems.

Which Steps to Rerun

Case 1 - MyGet Failure

No publication has occurred, so correct the problem and rerun.

Case 2 - NuGet Failure

One or more packages may have been published to MyGet. However, MyGet does not fail if you try to push a package version which has already been published. You may correct the problem and rerun.

Case 3 - Chocolatey Failure

Packages may have been published to NuGet, which does not handle re-publication well. You must run Chocolatey publication and the GitHub release separately.

Case 4 - GitHub Failure

Packages have been published already. You must run the GitHub production release step separately.

How to Rerun Steps

Recovery requires doing a local build, which exactly matches the build being published. This manual process is fragile but is the only one we have at this time. If in doubt, ask another team member for help.

Change to the v1-build branch on your local machine. Since all changes have already been merged, you may pull them to your machine. The build script needs to be run locally.

1. Do build -t CleanAll just to be sure that any leftover results are cleared out.
2. Do build -t BuildTestAndPackage to ensure that everything is working.
3. If you need to publish to NuGet or Chocolatey, edit the PublishPackages task in build.cake. Comment out the if clauses for the steps you do not want to run, i.e. those which already succeeded. Do build -t PublishPackages. Immediately after this succeeds, back out your edits.

NOTE: Yes, this is lame. We need to have separate targets for MyGet, NuGet and Chocolatey. Coming soon!

4. Do build -t CreateProductionRelease to perform the release on GitHub.

Limitations

1. This process does not yet support milestones with a pre-release suffix, like 1.5.0-beta2. This will be a future enhancement.

2. The CHANGES.txt file must currently be updated manually.

3. The Release Notes on the website must currently be updated manually.

4. User notification is currently manual.