diff --git a/.goreleaser.yml b/.goreleaser.yml index 257232faf..595659a30 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -25,7 +25,7 @@ changelog: regexp: "(?i)^.*(major|new provider|feature)[(\\w)]*:+.*$" order: 1 - title: 'Provider-specific changes:' - regexp: "(?i)^(akamaiedgedns|autodns|axfrddns|azure_dns|bind|cloudflareapi|cloudflareapi_old|cloudns|cscglobal|desec|digitalocean|dnsimple|dnsmadeeasy|domainnameshop|exoscale|gandi_v5|gcloud|hedns|hetzner|hexonet|hostingde|inwx|linode|msdns|namecheap|namedotcom|netcup|ns1|octodns|oracle|ovh|packetframe|powerdns|route53|softlayer|transip|vultr)[(\\w)]*:+.*$" + regexp: "(?i)((akamaiedge|autodns|axfrd|azure_dns|bind|cloudflare|cloudflareapi_old|cloudns|cscglobal|desec|digitalocean|dnsimple|dnsmadeeasy|domainnameshop|exoscale|gandi_v5|gcloud|hedns|hetzner|hexonet|hostingde|inwx|linode|msdns|namecheap|namedotcom|netcup|ns1|octodns|oracle|ovh|packetframe|powerdns|route53|softlayer|transip|vultr).*:)+.*" order: 2 - title: 'Depreciation warnings:' regexp: "(?i)^.*Deprecate[(\\w)]*:+.*$" diff --git a/docs/public/circleci_release.png b/docs/public/circleci_release.png new file mode 100644 index 000000000..735fdd1bf Binary files /dev/null and b/docs/public/circleci_release.png differ diff --git a/docs/release-engineering.md b/docs/release-engineering.md index 405845d40..3459023b4 100644 --- a/docs/release-engineering.md +++ b/docs/release-engineering.md @@ -6,90 +6,45 @@ title: How to build and ship a release # How to build and ship a release These are the instructions for producing a release. -Please change the version number as appropriate. +CircleCI will do most of the work for you. You will need to edit the draft release notes. -## Step 1. Tools check +Please change the version number as appropriate. Substitute (for example) +`3.19.0` any place you see `VERSION` in this doc. -Make sure you are using the latest version of `go` -(listed on [https://golang.org/dl/](https://golang.org/dl/)) +## Step 1. Tag the commit in master that you want to release -```bash -go version +```shell +git tag -a v3.19.0 +git push origin --tags ``` +See [Git Docs](https://git-scm.com/book/en/v2/Git-Basics-Tagging) for more examples. -## Step 2. Create a new release branch +Soon after +CircleCI will start a [build](https://app.circleci.com/pipelines/github/StackExchange/dnscontrol?branch=master) Workflow and produce all of the artifacts for the release. -From the "master" branch, run `bin/make-release.sh v3.xx.y` where -"v3.xx.y" should be the new release version. +![CircleCI Release Screenshot](public/circleci_release.png) -NOTE: This warning can be ignored: `error: failed to push some refs to 'github.com:StackExchange/dnscontrol.git'` +## Step 2. Create the release notes -The `make-release.sh` script will do the following: +The draft release notes are created for you. In this step you'll edit them. -1. Tag the current branch locally and remotely. -2. Update main.go with the new version string. -3. Create a file called draft-notes.txt which you will edit into the - release notes. -4. Print instructions on how to create the release PR. +The CircleCI build uses [GoReleaser](https://goreleaser.com/) which produces the [GitHub Release](https://github.com/StackExchange/dnscontrol/releases) with Release Notes derived from the commit history between now and the last tag. +These notes are just a draft and needs considerable editing. +You can also find a copy of the release notes in the CircleCI `release` job Artifacts. +These release notes will be used in multiple places (release notes, email announcements, etc.) +Release notes style guide: -NOTE: If you bump the major version, you need to change all the source -files. The last time this was done (v2 -> v3) these two commands -automated all that: - -```bash -# Make all the changes: -sed -i.bak -e 's@github.com.StackExchange.dnscontrol.v2@github.com/StackExchange/dnscontrol/v3@g' go.* $(fgrep -lri --include '*.go' github.com/StackExchange/dnscontrol/v2 *) -# Delete the backup files: -find * -name \*.bak -delete -``` - - -## Step 3. Verify the version string - -Verify the version string was updated: - -```bash -grep Version main.go -``` - -(Make sure that it lists the new version number.) - - -## Step 4. Make the PR - -The output of "make-release.sh" will mention a URL that will create the PR ("1. Create a PR:") - -Load the URL and make the PR. - - -## Step 5. Write the release notes. - -draft-notes.txt is just a draft and needs considerable editing. - -Once complete, the contents of this file will be used in multiple -places (release notes, email announcements, etc.) - -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 provier should begin with the all-caps -name of the provider, such as "ROUTE53: Added support for sandwiches (#100)" +* 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 provier should begin with the all-caps name of the provider, such as "ROUTE53: Added support for sandwiches (#100)" +* The `Depreciation warnings` section should just copy from `README.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](https://github.com/StackExchange/dnscontrol/releases) for recent release notes and copy that style. -The `Depreciation warnings` section should just copy from `README.md`. If you -change one, change it in the README too (you can make that change in this PR). - - Example/template: ```text @@ -110,58 +65,7 @@ Provider-specific changes: * CLOUDFLARE: Fix CF trying to update non-changeable TTL (#issueid) ``` - -## Step 6. Make the draft release. - -[On github.com, click on "Draft a new release"](https://github.com/StackExchange/dnscontrol/releases/new) - -Fill in the `Tag version` @ `Target` with: - - * Tag version: v$VERSION (this should be the first tag listed) - * Target: master (this should be the default; and disappears when - you enter the tag) - -Release title: Release v$VERSION - -Fill in the text box with the release notes written above. - -(DON'T click SAVE until the next step is complete!) - -(DO use the "preview" tab to proofread the text.) - - -## Step 7. Verify tests completed. - -By now the tests should have started running. - -Verify that the automated tests passed. If not, fix the problems -before you continue. - - -## Step 8. Merge - -Merge the PR. - -The tests will run again. - -Once they pass, you are ready to create and promote the release (see next step). - - -## Step 9. Publish the release - -a. Publish the release. - -* Make sure the "This is a pre-release" checkbox is NOT checked. -* Click "Publish Release". - -b. Wait for workflow to complete - -There's a GitHub Actions [workflow](https://github.com/StackExchange/dnscontrol/actions?query=workflow%3Arelease) which automatically builds and attaches -all 3 binaries to the release. Refresh the page after a few minutes and you'll -see dnscontrol-Darwin, dnscontrol-Linux, and dnscontrol.exe attached as assets. - - -## Step 10. Announce it via email +## Step 2. Announce it via email 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) @@ -177,8 +81,7 @@ https://github.com/StackExchange/dnscontrol/releases/tag/v$VERSION NOTE: You won't be able to post to the mailing list unless you are on it. [Click here to join](https://groups.google.com/forum/#!forum/dnscontrol-discuss). - -## Step 11. Announce it via chat +## Step 3. Announce it via chat Mention on [https://gitter.im/dnscontrol/Lobby](https://gitter.im/dnscontrol/Lobby) that the new release has shipped. @@ -186,31 +89,42 @@ Mention on [https://gitter.im/dnscontrol/Lobby](https://gitter.im/dnscontrol/Lob ANNOUNCEMENT: dnscontrol v$VERSION has been released! https://github.com/StackExchange/dnscontrol/releases/tag/v$VERSION ``` - -## Step 12. Get credit! +## Step 4. Get credit 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` +* Add the release to your weekly snippets +* Run this build: `dnscontrol_embed - Promote most recent artifact into ExternalDNS repo` +## Tip: How to bump the major version -# Tip: How to rebuild flattener +If you bump the major version, you need to change all the source +files. The last time this was done (v2 -> v3) these two commands +were used. They're included her for reference. + +```bash +# Make all the changes: +sed -i.bak -e 's@github.com.StackExchange.dnscontrol.v2@github.com/StackExchange/dnscontrol/v3@g' go.* $(fgrep -lri --include '*.go' github.com/StackExchange/dnscontrol/v2 *) +# Delete the backup files: +find * -name \*.bak -delete +``` + +## Tip: How to rebuild flattener Rebuilding flatter requites go1.17.1 and the gopherjs compiler. Install go1.17.1: -``` +```shell go install golang.org/dl/go1.17.1@latest go1.17.1 download ``` Install gopherjs: -``` +```shell go install github.com/gopherjs/gopherjs@latest ``` @@ -218,15 +132,14 @@ Build the software: NOTE: GOOS can't be Darwin because GOPHERJS doesn't support it. -``` +```shell cd docs/flattener export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)" export GOOS=linux gopherjs build ``` - -# Tip: How to update modules +## Tip: How to update modules List out-of-date modules and update any that seem worth updating: diff --git a/main.go b/main.go index 6434ac9ab..c947f4a3a 100644 --- a/main.go +++ b/main.go @@ -16,10 +16,9 @@ import ( // Version management. Goals: // 1. Someone who just does "go get" has at least some information. // 2. If built with build/build.go, more specific build information gets put in. -// Update the number here manually each release, so at least we have a range for go-get people. var ( SHA = "" - Version = "v3.18.1" + Version = "" BuildTime = "" )