mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
DOCS: Update with new release process (#1707)
* 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
GitHub
@ -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)]*:+.*$"
|
||||
|
||||
BIN
docs/public/circleci_release.png
Normal file
BIN
docs/public/circleci_release.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 80 KiB |
@ -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.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
3
main.go
3
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 = ""
|
||||
)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user