StackExchange/dnscontrol
1
1
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2025-10-27 22:48:27 +08:00
Code Issues Projects Releases Packages Wiki Activity

DOCS: Update with new release process (#1707)

Browse source 
* Update with new release process

* Move major bump to its own section; split step 1 into 2 parts

* Remove version number from main.go

* Linting

* Add example `git tag` command

* Try a different regex pattern for release note generation

Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>
This commit is contained in:
Chris Hunt 2022-08-15 10:41:45 -04:00 • committed by GitHub
parent 9eda756a1b
commit cfc82c8e13
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 47 additions and 135 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.goreleaser.yml
View file

@ -25,7 +25,7 @@ changelog:
regexp: "(?i)^.*(major|new provider|feature)[(\\w)]*:+.*$" regexp: "(?i)^.*(major|new provider|feature)[(\\w)]*:+.*$"
order: 1 order: 1
- title: 'Provider-specific changes:' - 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 order: 2
- title: 'Depreciation warnings:' - title: 'Depreciation warnings:'
regexp: "(?i)^.*Deprecate[(\\w)]*:+.*$" regexp: "(?i)^.*Deprecate[(\\w)]*:+.*$"

BIN
docs/public/circleci_release.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 80 KiB

177
docs/release-engineering.md
View file

@ -6,90 +6,45 @@ title: How to build and ship a release
# How to build and ship a release # How to build and ship a release
These are the instructions for producing 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` ## Step 1. Tag the commit in master that you want to release
(listed on [https://golang.org/dl/](https://golang.org/dl/))
```bash ```shell
go version 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 ![CircleCI Release Screenshot](public/circleci_release.png)
"v3.xx.y" should be the new release version.
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. 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.
2. Update main.go with the new version string. These notes are just a draft and needs considerable editing.
3. Create a file called draft-notes.txt which you will edit into the You can also find a copy of the release notes in the CircleCI `release` job Artifacts.
release notes. These release notes will be used in multiple places (release notes, email announcements, etc.)
4. Print instructions on how to create the release PR.
Release notes style guide:
NOTE: If you bump the major version, you need to change all the source * 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".
files. The last time this was done (v2 -> v3) these two commands * Every item should include the ID of the issue related to the change. If there was no issue, create one and close it.
automated all that: * 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)"
```bash * 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).
# 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)"
See [https://github.com/StackExchange/dnscontrol/releases for examples](https://github.com/StackExchange/dnscontrol/releases) for recent release notes and copy that style. 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: Example/template:
```text ```text
@ -110,58 +65,7 @@ Provider-specific changes:
* CLOUDFLARE: Fix CF trying to update non-changeable TTL (#issueid) * CLOUDFLARE: Fix CF trying to update non-changeable TTL (#issueid)
``` ```
## Step 2. Announce it via email
## 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
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) 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 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). it. [Click here to join](https://groups.google.com/forum/#!forum/dnscontrol-discuss).
## Step 3. Announce it via chat
## Step 11. Announce it via chat
Mention on [https://gitter.im/dnscontrol/Lobby](https://gitter.im/dnscontrol/Lobby) that the new release has shipped. 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 ANNOUNCEMENT: dnscontrol v$VERSION has been released! https://github.com/StackExchange/dnscontrol/releases/tag/v$VERSION
``` ```
## Step 4. Get credit
## Step 12. Get credit!
Mention the fact that you did this release in your weekly accomplishments. Mention the fact that you did this release in your weekly accomplishments.
If you are at Stack Overflow: If you are at Stack Overflow:
* Add the release to your weekly snippets * Add the release to your weekly snippets
* Run this build: `dnscontrol_embed - Promote most recent artifact into ExternalDNS repo` * 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. Rebuilding flatter requites go1.17.1 and the gopherjs compiler.
Install go1.17.1: Install go1.17.1:
``` ```shell
go install golang.org/dl/go1.17.1@latest go install golang.org/dl/go1.17.1@latest
go1.17.1 download go1.17.1 download
``` ```
Install gopherjs: Install gopherjs:
``` ```shell
go install github.com/gopherjs/gopherjs@latest 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. NOTE: GOOS can't be Darwin because GOPHERJS doesn't support it.
``` ```shell
cd docs/flattener cd docs/flattener
export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)" export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)"
export GOOS=linux export GOOS=linux
gopherjs build gopherjs build
``` ```
## Tip: How to update modules
# Tip: How to update modules
List out-of-date modules and update any that seem worth updating: List out-of-date modules and update any that seem worth updating:

3
main.go
View file

@ -16,10 +16,9 @@ import (
// Version management. Goals: // Version management. Goals:
// 1. Someone who just does "go get" has at least some information. // 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. // 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 ( var (
SHA = "" SHA = ""
Version = "v3.18.1" Version = ""
BuildTime = "" BuildTime = ""
) )