Merge pull request #1054 from actions/ahpook/release-4.8.3

Changes for Release 4.8.3

Author: ahpook

CONTRIBUTING.md

@@ -50,8 +50,7 @@ Before you begin, you need to have [Node.js](https://nodejs.org/en/) installed,
 
 #### Manually testing for vulnerabilities
 
-We have a script to scan a given PR for vulnerabilities, this will
-help you test your local changes. Make sure to [grab a Personal Access Token (PAT)](https://github.com/settings/tokens) before proceeding (you'll need `repo` permissions for private repos):
+We have a script to scan a given PR for vulnerabilities, which will help you test your local changes. Make sure to [grab a Personal Access Token (PAT)](https://github.com/settings/tokens) before proceeding (you'll need `repo` permissions for private repos):
 
 <img width="480" alt="Screen to create a PAT with a note of `dr-token`, 30 day duration (expiring Jun 11, 2022), with `repo` scopes selected" src="https://user-images.githubusercontent.com/2161/168026161-16788a0a-b6c8-428e-bb6a-83ea2a403070.png">
 
@@ -106,38 +105,34 @@ Here are a few things you can do that will increase the likelihood of your pull
 
 _Note: these instructions are for maintainers_
 
-1. Update the version number in [package.json](https://github.com/actions/dependency-review-action/blob/main/package.json) and run `npm i` to update the lockfile.
-1. Update the dist files by running `npm run build` and `npm run package`
-1. Go to [Draft a new
-   release](https://github.com/actions/dependency-review-action/releases/new)
-   in the Releases page.
-1. Make sure that the `Publish this Action to the GitHub Marketplace`
-   checkbox is enabled
+- Create a local branch based on the `main` of the upstream repo.
+- Update the version number in [package.json](https://github.com/actions/dependency-review-action/blob/main/package.json) and run `npm i` to update the lockfile.
+- Update the dist files by running `npm run build` and `npm run package`
+- Go to [Draft a new release](https://github.com/actions/dependency-review-action/releases/new) in the Releases page.
+- Make sure that the `Publish this Action to the GitHub Marketplace` checkbox is enabled
 
 <img width="481" alt="Screen showing Release Action with Publish this Action to the GitHub Marketplace checked" src="https://user-images.githubusercontent.com/2161/173822484-4b60d8b4-c674-4bff-b5ff-b0c4a3650ab7.png">
 
-3. Click "Choose a tag" and then "Create new tag", where the tag name
-   will be your version prefixed by a `v` (e.g. `v1.2.3`).
-4. Use a version number for the release title (e.g. "1.2.3").
+- Click "Choose a tag" and then "Create new tag", where the tag name
+  will be your version prefixed by a `v` (e.g. `v1.2.3`).
+- Use a version number for the release title (e.g. "1.2.3").
 
 <img width="700" alt="Create an action release in categories Security + Dependency management from branch main creating tag v2.0.0 on publish" src="https://user-images.githubusercontent.com/2161/173822548-33ab3432-d679-4dc1-adf8-b50fdaf47de3.png">
 
-5. Add your release notes. If this is a major version make sure to
-   include a small description of the biggest changes in the new version.
-6. Click "Publish Release".
+- Add your release notes. If this is a major version make sure to include details about any breaking changes in the new version.
+- Click "Publish Release".
 
-You now have a tag and release using the semver version you used
-above. The last remaining thing to do is to move the dynamic version
-identifier to match the current SHA. This allows users to adopt a
-major version number (e.g. `v1`) in their workflows while
-automatically getting all the
-minor/patch updates.
+You now have a tag and release using the semver version you used above. The last remaining thing to do is to update the major version branch to match the current release. This allows users to adopt a major version number (e.g. `v4`) in their workflows while automatically getting all the minor/patch updates.
 
-To do this just checkout `main`, force-create a new annotated tag, and push it:
+As of v4.8.3, we use a **branch** (not a force-pushed tag) for the major version pointer. This is important because force-pushing tags breaks GitHub's auto-generated release changelog links (see [#1035](https://github.com/actions/dependency-review-action/issues/1035)) and violates git's (unenforced) expectation that tags are immutable.
+
+To update the major version branch:
 
 ```
-git tag -fa v4 -m "Updating v4 to 4.0.1"
-git push origin v4 --force
+git checkout main
+git pull origin main
+git branch -f v4 HEAD
+git push origin v4
 ```
 
 </details>