# Pre-Releases
Since version 1.63 VS Code has supported [pre-release extensions](https://code.visualstudio.com/updates/v1_63#_pre-release-extensions). We sometimes publish a pre-release version of our extension, for example to give early adopters a chance to try a major new feature before it reaches the regular extension.

For instance we published the `1.5.*` pre-releases when migrating to a new credential storage architecture provided by InterSystems Server Manager version 3, itself also initially published as a pre-release.

We reserve the odd numbers in the minor part of the version number exclusively for pre-releases, and we keep the version number of an active pre-release extension higher than that of the regular one.

Instead of using sequential integers beginning at 0 in the maintenance part of their version, pre-releases use a YYYYMMDDnn format. For example, `1.5.2022022801` was the first (and typically only) pre-release published on 28th February 2022. This convention also helps make pre-releases more easily spotted.

## The `prerelease` branch
Features that are initially only going into the pre-release extension get developed on branches of the `prerelease` branch, which like `master` is a protected branch (i.e. it doesn't accept pushes, only PR merges). We recommend using a `pre-` prefix on the names of branches you create from the `prerelease` branch, as a way of reminding you to create the subsequent PR into the `prerelease` branch rather than `master`.

## Updating `prerelease` from `master`
Regular development and bugfixing is done with PRs that merge into `master` once they have been approved. Over time, `prerelease` therefore falls behind `master`, though it continues to contain pre-release features that are not present in `master`.

Every time a release is done from `master` (maintenance, minor or major) it is a good idea to get `master`'s new features into `prerelease`. Here's how:

1. Switch to the `prerelease` branch of your local copy of the repository, and make sure your local copy is up-to-date with the repo branch.
2. Create a local branch called `pre-sync-X.Y.Z` where `X.Y.Z` is the version number of the most recent release from `master`.
3. Merge the repo's `master` branch into your `pre-sync-X.Y.Z` branch. Resolve all conflicts. Test the extension locally.
4. Stage and commit your changes, then push `pre-sync-X.Y.Z`.
5. Create a PR that will merge this branch into `prerelease`. Take care not to target `master`, which will be the default.
6. After the PR has been approved, merge it. Delete `pre-sync-X.Y.Z`.

## Publishing the Pre-Release extension
1. [Draft a new release](https://github.com/intersystems-community/vscode-objectscript/releases/new).
   - Make sure you pick `prerelease` as the target branch (the default is `master`).
   - In the "Choose a tag" field, type a new tag. For instance if you are doing this on 28th February 2022 after merging `pre-sync-1.4.4` the pre-release tag name must be `v1.5.2022022801` -- be sure to remember the `v` prefix.
   - Use the same string for the release title as you used for the new tag, e.g. `v1.5.2022022801`
   - For the release description the phrase "See CHANGELOG for details" is adequate.
   - Leave the "This is a pre-release" checkbox UNCHECKED. What GitHub calls a pre-release is not the same kind of thing as we are about to publish on Marketplace.
2. Click "Publish release".

Our CI workflow (GitHub Actions) will build a pre-release VSIX and publish it.