Skip to content

Latest commit

 

History

History
132 lines (101 loc) · 4.71 KB

RELEASE.md

File metadata and controls

132 lines (101 loc) · 4.71 KB
Raw

Releasing Scorecard

This is a draft document to describe the release process for Scorecard

(If there are improvements you'd like to see, please comment on the tracking issue or issue a pull request to discuss.)

Tracking

As the first task, a Release Manager should open a tracking issue for the release.

We don't currently have a template for releasing, but the following issue is a good example to draw inspiration from.

We're not striving for perfection with the template, but the tracking issue will serve as a reference point to aggregate feedback, so try your best to be as descriptive as possible.

Preparing the release

This section covers changes that need to be issued as a pull request and should be merged before releasing the scorecard GitHub Action.

Validate tests

Check the unit tests and integration tests are passing for the planned release commit, either locally or for the GitHub workflows.

Validate the changes with scdiff

  1. Create the list of repos to use for the analysis if you don't have it already:
cat <<EOF > repos.txt
https://github.com/airbnb/lottie-web
https://github.com/apache/tomcat
https://github.com/Azure/azure-functions-dotnet-worker
https://github.com/cncf/xds
https://github.com/google/go-cmp
https://github.com/google/highwayhash
https://github.com/googleapis/google-api-php-client
https://github.com/jacoco/jacoco
https://github.com/ossf/scorecard
https://github.com/pallets/jinja
https://github.com/polymer/polymer
https://github.com/rust-random/getrandom
https://github.com/yaml/libyaml
https://gitlab.com/baserow/baserow
https://gitlab.com/cryptsetup/cryptsetup
EOF
  1. Run scdiff on the previous release:
git checkout <old release tag>
go run cmd/internal/scdiff/main.go generate --repos repos.txt --output oldRelease.json
  1. Run scdiff on the commit to be tagged:
git checkout <commit to be tagged>
go run cmd/internal/scdiff/main.go generate --repos repos.txt --output newRelease.json
  1. Compare the results:
go run cmd/internal/scdiff/main.go compare oldRelease.json newRelease.json
  1. Evaluating results: There will be differences! That's ok, but please pay attention to what they are and use your judgement when evaluating them. Compare the changes against the release notes you're expecting below.

Drafting release notes

Release notes are a semi-automated process. We often start by opening drafting a new release on GitHub. You can select to create a new tag on publish, and auto-generate some notes by clicking Generate release notes. This provides a good start, but no one wants to see a wave of dependabot commits, so filter them out. Try to focus on the PRs that affect users or behavior, not dependency updates or CI changes.

Using the Kubernetes release-notes tool can also be helpful if PR authors filled out the user-facing change section.

release-notes --org ossf --repo scorecard --branch main \
  --dependencies=false \
  --required-author "" \
  --start-rev <previous release tag> \
  --end-rev <commit to be tagged>

Note: This doesn't always grab the right value when PR bodies have multiple code blocks in them.

Save your draft when satisfied and share it with other maintainers for feedback, if possible.

Release

Create a tag

The GitHub release process supports creating a tag on publish, but prefer signing the tag when possible. In this example, we're releasing a hypothetical v100.0.0 at the desired commit SHA SHA:

git remote update
git checkout `SHA`
git tag -s -m "v100.0.0" v100.0.0
git push <upstream> v100.0.0

Create a GitHub release

Revisit the draft release you created earlier, and ensure it's using the correct tag.

Release title: <tag>

The release notes will be the notes you drafted in the previous step.

Ensure the release is marked as the latest release, if appropriate.

Click Publish release.

Validate Release

When a new tag is pushed, our GitHub Actions will create a release using goreleaser. Confirm the workflow ran without issues. Check the release again to verify the artifacts and provenance have been added.

If any issues were encountered, fixes must be issued under a new release/tag as Go releases are immutable.