Update contributing doc (#40)

* Update contributing doc

* Update preview.yml

.github/workflows/pre-release.yml → .github/workflows/preview.yml

@@ -2,6 +2,9 @@ name: "Publish Preview"
 
 on:
   workflow_dispatch:
+  push:
+    branches:
+      - main
 
 jobs:
   build-and-publish:

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: "Publish"
+name: "Publish Release"
 
 on:
   workflow_dispatch:

CONTRIBUTING.md

@@ -1,14 +1,25 @@
 # Contributing
 
-## Releases
+## Publishing
 
-This extension is automatically built and released by the [`Build and Publish Vercel Deployment Extension`](./.github/workflows/ci.yml) CI workflow. The workflow invokes the [build-and-publish.js](./scripts/build-and-publish.js) script. This script requires a environment variable `AZURE_TOKEN`. This variable must be an [Azure DevOps Personal Access Token with the `Marketplace: Publish` permission](https://learn.microsoft.com/en-us/azure/devops/extend/publish/command-line?view=azure-devops#create-a-personal-access-token). The environment variable is passed to the script as a [GitHub Actions encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository).
+### Build and Publish Script
 
-> The current `AZURE_TOKEN` secret was generated by @Ethan-Arrowood. It expires on June 24th, 2024.
+The [build-and-publish.js](./scripts/build-and-publish.js) script is used for both private preview and public release publishing. It runs the [tfx-cli](https://www.npmjs.com/package/tfx-cli) dependency, which is the official Node.js CLI for Azure DevOps. Source code and documentation for this can be found here [microsoft/tfs-cli](https://github.com/microsoft/tfs-cli) (yes, the names do not match 🤷‍♂️). The `tfx-cli` will fail if the version number in [vss-extension.json](./vss-extension.json) has not been changed.
 
-The automatic process runs on every new commit to the `main` branch. It runs the [tfx-cli](https://www.npmjs.com/package/tfx-cli), which is the official Node.js CLI for Azure DevOps. Source code and documentation for this can be found here [microsoft/tfs-cli](https://github.com/microsoft/tfs-cli) (yes the names do not match 🤷‍♂️). The `tfx-cli` will fail if the version number in [vss-extension.json](./vss-extension.json) has not been changed.
+The script requires an environment variable `AZURE_TOKEN`. This variable must be an [Azure DevOps Personal Access Token with the `Marketplace: Publish` permission](https://learn.microsoft.com/en-us/azure/devops/extend/publish/command-line?view=azure-devops#create-a-personal-access-token). The environment variable is passed to the script as a [GitHub Actions encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository).
+
+> The current `AZURE_TOKEN` secret was generated by Vercel's IT department in August 2024 and will expire in August 2025. If the token expires, a new token must be generated and the secret updated in the GitHub repository.
+
+### Private Preview
+
+The extension is automatically built and released as a private preview by the [`Publish Preview`](./.github/workflows/preview.yml) CI workflow. The workflow first replaces some values in the [`vss-extension.json`](./vss-extension.json) file to make the extension private, and the task json files to make the tasks private and unique. It then builds and publishes the extension to the Visual Studio Marketplace using the build-and-publish script.
+
+### Public Release
+
+For public releases, there is a CI workflow that must be manually triggered called [`Publish Release`](./.github/workflows/release.yml). This workflow publishes the extension with all of the existing values in the extension and task json files, using the build-and-publish script.
 
 To create a new release:
+
 - Either within the feature/fix PR, or afterwards, update the task versions in the respective task.json file(s).
   - The versions follow [SemVer](https://semver.org/).
     - Increment `Patch` for **Fixes**.
@@ -22,4 +33,5 @@ To create a new release:
     - As an example, if one task receives a `Patch` update, and the other receives a `Minor` update, then the extension version should increment its `Minor` version (and subsequently reset the `Patch` value to `0`).
     - If you are unsure, consult with the Vercel CLI team before pushing version changes.
 - After modifying the version values, create and push a commit, and open a PR against `main`.
-- Once merged to `main`, the CI will automatically run, and if the extension version value has changed, the workflow will succeed and the new version will be published to Visual Studio Marketplace.
+- Once merged to `main`, the CI will automatically publish a private preview version of the extension to the Visual Studio Marketplace.
+- After testing the preview version, manually run the `Publish Release` workflow to publish the extension to the public marketplace.