Comment on page
How to build and ship a release
These are the instructions for producing a release.
GitHub Actions (GHA) will do most of the work for you. You will need to edit the draft release notes and click a button to make the release public.
Please change the version number as appropriate. Substitute (for example)
v4.2.0 any place you see $VERSION in this doc.export VERSION=v4.2.0
git checkout master
git pull
go fmt ./...
go generate ./...
go mod tidy
git commit -a -m "Update generated files for $VERSION"
export VERSION=v4.2.0
git tag -m "Release $VERSION" -a $VERSION
git push origin --tags
Soon after GitHub will start an Action Workflow called "draft release" which will build all release binaries and write the draft release notes.
The draft release notes are created for you. In this step you'll edit them.
The GHA workflow uses GoReleaser which produces the GitHub Release with Release Notes derived from the commit history between now and the last tag. These notes are just a draft and needs considerable editing. These release notes are used elsewhere, in particular the email step.
Release notes style guide:
- Entries in the bullet list should be phrased in the positive: "Feature FOO now does BAR". This is often the opposite of the related issue, which was probably phrased, "Feature FOO is broken because of BAR".
- Every item should include the ID of the issue related to the change. If there was no issue, create one and close it.
- Sort the list most important/exciting changes earlier in the list.
- Items related to a specific provider should begin with the all-caps name of the provider, such as "ROUTE53: Added support for sandwiches (#100)"
- The
Deprecation warningssection should just copy fromREADME.md. If you change one, change it in the README too (you can make that change in this PR).
See https://github.com/StackExchange/dnscontrol/releases for examples for recent release notes and copy that style.
Template:
## Changelog
This release includes many new providers (FILL IN), dozens
of bug fixes, and FILL IN.
### Breaking changes:
* FILL IN
### Major features:
* FILL IN
### Provider-specific changes:
* FILL IN
### Other changes and improvements:
* FILL IN
### Deprecation warnings:
Email the release notes to the mailing list: (note the format of the Subject line and that the first line of the email is the URL of the release)
Subject: New release: dnscontrol v$VERSION
https://github.com/StackExchange/dnscontrol/releases/tag/v$VERSION
[insert the release notes here]
ANNOUNCEMENT: dnscontrol v$VERSION has been released! https://github.com/StackExchange/dnscontrol/releases/tag/v$VERSION
Mention the fact that you did this release in your weekly accomplishments.
If you are at Stack Overflow:
- Add the release to your weekly snippets
- Run this build:
dnscontrol_embed - Promote most recent artifact into ExternalDNS repo
If you bump the major version, you need to change all the source files. The last time this was done (v3 -> v4) these two commands were used. They're included her for reference.
# Make all the changes:
sed -i.bak -e '[email protected]@github.com/StackExchange/dnscontrol/v4@g' go.* $(fgrep -lri --include '*.go' github.com/StackExchange/dnscontrol/v3 *)
# Delete the backup files:
find * -name \*.bak -delete
GHA is configured to run an integration test for any provider listed in the "provider" list. However the test is skipped if the
*_DOMAIN variable is not set. For example, the Google Cloud provider integration test is only run if GCLOUD_DOMAIN is set.- Q: Where is the list of providers to run integration tests on?
- A: In
.github/workflows/pr_test.yml: (1) the "PROVIDERS" list, (2) theintegrtests-diff2section. - Q: Where are non-secret environment variables stored?
- A: GHA calls them "Variables". Update them here: https://github.com/StackExchange/dnscontrol/settings/variables/actions
- Q: Where are SECRET environment variables stored?
- A: GHA calls them "Secrets". Update them here: https://github.com/StackExchange/dnscontrol/settings/secrets/actions
- 1.Edit
.github/workflows/pr_test.yml - 2.Add the
FOO_DOMAINvariable name of the provider to the "PROVIDERS" list. - 3.Set the
FOO_DOMAINvariables in GHA via https://github.com/StackExchange/dnscontrol/settings/variables/actions - 4.All other variables should be stored as secrets (for consistency). Add them to the
integration-testssection. Set them in GHA via https://github.com/StackExchange/dnscontrol/settings/secrets/actions
Overview: You will fork the repo and add any secrets to your fork. For security reasons you won't have access to the secrets from the main repository.
- 1.If you already have a fork, be sure to use the "sync fork" button on the main page to sync with master.
- 2.In your fork, set the
${DOMAIN}_DOMAINvariable in GHA via Settings :: Secrets and variables :: Actions :: Variables. - 3.In your fork, set any secrets in GHA via Settings :: Secrets and variables :: Actions :: Secrets.
- 4.Start a build
Rebuilding flatter requires go1.17.1 and the gopherjs compiler.
Install go1.17.1:
go install golang.org/dl/go1.17.1@latest
go1.17.1 download
go install github.com/gopherjs/gopherjs@latest
Build the software:
NOTE: GOOS can't be Darwin because GOPHERJS doesn't support it.
cd docs/flattener/
export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)"
export GOOS=linux
gopherjs build
List out-of-date modules and update any that seem worth updating:
go install github.com/oligot/go-mod-upgrade@latest
go-mod-upgrade
go mod tidy
OLD WAY:
go install github.com/psampaz/go-mod-outdated@latest
go list -mod=mod -u -m -json all | go-mod-outdated -update -direct
# If any are out of date, update via:
go get module/path
# Once the updates are complete, tidy up:
go mod tidy
Last modified 5d ago