docs/howto/release-git-lfs.md: add security steps

The documentation of our standard and patch release processes does not,
at present, include the steps required to build a security patch release,
so we add two sections which describe how we build such releases.

The first new section documents our normal security patch release
process, which applies when we do not need to coordinate our release
with other projects, or at least do not need to build release assets
in private while under a publication embargo.

The second new section details the process of building new Git LFS
release binaries in private, so they can be shared with other downstream
projects while we are under an embargo on the publication of the
security vulnerability and associated security patch release.

Author: chrisd8088

docs/howto/release-git-lfs.md

@@ -337,3 +337,269 @@ and then use that branch as the base for the PATCH release.
 
   5. Then follow the [guidelines](#building-a-release) above, using the
      `release-M.N` branch as the base for the new PATCH release.
+
+### Building security PATCH versions
+
+In our public security [policy](../../SECURITY.md) we request that
+potential vulnerabilities in the Git LFS client be reported to us
+via email.  Users sometimes also choose to open draft GitHub security
+advisories, although we do not encourage that option.
+
+If we determine that such a report is valid, we develop a PATCH release
+version of the client with a remediation for the security issue,
+following the steps below.
+
+  1. Open a new draft security advisory, fill out the relevant
+     details in the
+     [template](https://github.com/git-lfs/git-lfs/security/advisories/new),
+     and request a CVE identifier.
+
+  2. Create a temporary private fork of this repository from the draft
+     security advisory page, and use the fork to develop a resolution
+     of the vulnerability.
+
+  3. Create two PRs in the private fork, one to remediate the vulnerability
+     in the `main` development branch of the public `git-lfs/git-lfs`
+     repository, and one to do so in the appropriate `release-M.N` branch.
+
+     The PR which targets the release branch should have a final, extra
+     commit which adds an entry for the new PATCH release version in the
+     `CHANGELOG.md` file, describing the release and the security fix it
+     contains.  This commit should also include the changes generated
+     by the `script/update-version vM.N.P` command, as per the second step
+     in our standard release process.
+
+     If the `release-M.N` branch does not exist in the public repository,
+     create it as per our regular PATCH release process, and then create
+     the second PR in the private fork against the new branch.  Be prepared
+     to proceed relatively quickly, since the appearance of the new branch
+     serves as a public notice that we may be publishing a PATCH release
+     shortly.
+
+  4. From the draft security advisory page, use the "Merge pull requests"
+     option to merge both PRs simultaneously.
+
+     Note that both the release branch and the `main` branch in the private
+     fork must be up-to-date with the corresponding branches in the public
+     repository in order for the GitHub UI to determine whether the PRs have
+     no merge conflicts.
+
+  5. Publish the security advisory.
+
+  6. Follow our standard release process, starting with the step in which
+     we create a GPG-signed tag named `vM.N.P` on the merge commit to the
+     `release-M.N` branch.
+
+  7. After publication of the new release, update the `git-lfs.com` home
+     page with a banner message regarding the security PATCH release
+     by pushing a change to the `_includes/home/secondary.html` file
+     in the `git-lfs/git-lfs.github.com` repository.
+
+  8. Create a new discussion in the "Announcements" section of the GitHub
+     discussion [forum](https://github.com/git-lfs/git-lfs/discussions)
+     describing the security PATCH release, and pin the discussion for
+     all categories in the forum.
+
+### Building security PATCH versions under embargo
+
+When coordinating the release of a security patch with one or more
+other projects, we must not follow the processes described above as
+they depend on the GitHub Actions release workflow in our public
+`git-lfs/git-lfs` repository.  Instead, we use a private repository
+with a modified release workflow to build the binaries and packages
+for our new version so that we can share them with the other projects
+in advance of the coordinated release date.
+
+  1. Open a draft security advisory, apply for a CVE identifier, and
+     create a private fork in which to develop a resolution of the
+     vulnerability, as described above in the initial steps of our
+     non-embargoed security PATCH release process.
+
+  2. Create one PR in the private fork to remediate the vulnerability
+     in the `main` development branch of the public repository.
+
+  3. Create a branch in the private fork from the appropriate
+     `release-M.N` branch, or if that does not yet exist, from the
+     appropriate `vM.N.0` tag, and add the necessary changes to remediate
+     the vulnerability.
+
+     This branch should have one extra, final commit which adds an entry
+     for the new PATCH release version in the `CHANGELOG.md` file,
+     describing the release and the security fix it contains.  This
+     commit should also include the changes generated by the
+     `script/update-version vM.N.P` command, as per the second step
+     in our standard release process.
+
+  4. Pull this branch from the private fork of the public repository
+     and push it into a separate private repository which has a fresh copy
+     of the public `git-lfs/git-lfs` repository, and for which our full
+     CI and release GitHub Actions workflows are configured and enabled.
+
+     Note that the private fork created from the draft security advisory
+     will not execute GitHub Actions jobs, and so we require the use of
+     a separate private repository to run a modified release workflow.
+
+  5. If the `release-M.N` branch does not exist, create it in the
+     separate private repository from the `vM.N.0` tag, as described
+     in the second step of our regular PATCH release process.
+
+  6. Merge the branch containing the security fix and the commit with the
+     new `CHANGELOG.md` entry (and `script/update-version vM.N.P` changes)
+     into the `release-M.N` branch, and sign the merge commit with your
+     GPG key:
+
+     ```ShellSession
+     $ git checkout release-M.N
+     $ git merge --no-ff -S \
+         -m "Merge pull request from GHSA-abcd-1234-wxyz" \
+         -m "release: M.N.P" \
+         branch-with-fix-and-changelog
+     ```
+
+     Use the GHSA identifier from the draft security advisory in the
+     merge commit's description.
+
+  7. Create a GPG-signed tag named `vM.N.P` on the merge commit, using
+     the same command from the equivalent step of our standard release
+     process:
+
+     ```ShellSession
+     $ git tag -s vM.N.P -m vM.N.P
+     ```
+
+  8. Check out the `main` branch of the private repository and make
+     several revisions to the `.github/workflows/release.yml` file,
+     and then push these changes back to the private repository's `main`
+     branch.
+
+     First, change the `on` value to `workflow_dispatch`:
+
+     ```diff
+     -on:
+     -  push:
+     -    tags: '*'
+     +on: workflow_dispatch
+     ```
+
+     Set the version of Go in each `matrix` context to the same version
+     used in the Dockerfiles from our `git-lfs/build-dockers` repository.
+
+     Replace the `${{ github.ref }}` context wherever it appears with the
+     `vM.N.P` tag:
+
+     ```diff
+     -    ref: ${{ github.ref }}
+     +    ref: vM.N.P
+     ```
+
+     Revise the `build-docker` and `build-docker-arm` jobs so they do not
+     upload the Linux packages generated by the `docker/run_dockers.bsh`
+     script to Packagecloud by running the `script/packagecloud.rb` utility.
+     Change the jobs to instead upload the Linux packages as job artifacts;
+     for instance, for the `build-docker` job:
+
+     ```yaml
+         - uses: actions/upload-artifact@v4
+           with:
+             name: docker-assets
+             path: |
+               repos/**/*.deb
+               repos/**/*.rpm
+     ```
+
+     Make sure to use distinct artifact `name`s for each of these jobs,
+     i.e., `docker-assets` and `docker-arm-assets`.
+
+  9. Push the `vM.N.P` tag to the private repository, and then cancel
+     the GitHub Actions job which runs from the release workflow.
+
+     (This workflow will run because the tag includes our normal
+     GitHub Actions workflow definitions without the changes made in
+     the previous step, since those exist only on the `main` branch,
+     and we do not want to include these temporary workflow changes in
+     the security release itself.)
+
+     Confirm that the CI workflow job succeeds.
+
+ 10. From the private repository's GitHub Actions page, manually dispatch
+     the release workflow.
+
+ 11. When the manually-dispatched job is complete, download the
+     `release-assets`, `docker-assets`, and `docker-arm-assets` archive
+     files from the "Artifacts" section of the job's "Summary" page.
+
+     Share the relevant binaries from the archive files with the other
+     collaborating projects during the embargo period.
+
+ 12. Before the embargo is due to the lifted, unpack the `release-assets`
+     archive file at the top level of this repository and use the
+     `script/upload` utility to create a draft release announcement and
+     attach the release assets to it, just as for a standard release:
+
+     ```ShellSession
+     $ rm -rf bin/releases
+     $ unzip /path/to/release-assets.zip
+
+     $ script/upload --skip-verify vM.N.P
+     ```
+
+ 13. When the embargo is lifted, use the "Merge pull requests" option
+     on the draft security advisory page to merge the PR with the security
+     fix into the `main` branch of the public repository.
+
+     Note that the `main` branch in the private fork must be up-to-date
+     with the corresponding branch in the public repository in order for
+     the GitHub UI to determine whether the PR has no merge conflicts.
+
+ 14. Publish the security advisory.
+
+ 15. Pull the `release-M.N` branch and `vM.N.P` tag from the private
+     repository where the release workflow was run manually, and push
+     them into the public `git-lfs/git-lfs` repository.
+
+     Immediately cancel the GitHub Actions job which runs from the
+     release workflow in the public repository.
+
+     Note that cancelling the release workflow job is important, since
+     it will otherwise build new versions of the RPM and Debian Linux
+     packages and publish them to Packagecloud.
+
+ 16. Upload to Packagecloud the RPM and Debian Linux packages in the
+     `docker-assets` and `docker-arm-assets` archive files created earlier
+     by the manual release workflow job.
+
+     Note that the `script/packagecloud.rb` utility requires the
+     `PACKAGECLOUD_TOKEN` environment variable to contain the current
+     Packagecloud account credential token.
+
+     ```ShellSession
+     $ mkdir repos
+     $ unzip -d repos /path/to/docker-assets.zip
+     $ unzip -d repos /path/to/docker-arm-assets.zip
+
+     $ gem install packagecloud-ruby
+     $ PACKAGECLOUD_TOKEN="<token>" script/packagecloud.rb
+     ```
+
+ 17. Finalize the release process using the `script/upload` utility with
+     the `--finalize` option.  The script will add GPG signatures to the
+     `hashes` and `sha256sums` files and then upload the signed files:
+
+     ```ShellSession
+     $ script/upload --finalize vM.N.P
+     ```
+
+ 18. Publish the release announcement.
+
+ 19. Update the `_config.yml` file in the `git-lfs/git-lfs.github.com`
+     repository with the new `M.N.P` release version and push the change,
+     as described in the final steps of our standard release process.
+
+     In addition, update the `_includes/home/secondary.html` file with
+     a banner message regarding the security PATCH release, and push
+     the change.
+
+ 20. Create a new discussion in the "Announcements" section of the GitHub
+     discussion [forum](https://github.com/git-lfs/git-lfs/discussions)
+     describing the security PATCH release, and pin the discussion for
+     all categories in the forum.