From 3903e8059eadc9e255007e6c01e3bdfa32d1628e Mon Sep 17 00:00:00 2001 From: John Kerl Date: Mon, 7 Mar 2022 23:38:13 -0500 Subject: [PATCH] Freshen notes on how to create a release --- docs/mkdocs.yml | 1 + docs/src/build.md | 68 ----------------------------------- docs/src/build.md.in | 68 ----------------------------------- docs/src/contributing.md | 4 +++ docs/src/contributing.md.in | 4 +++ docs/src/how-to-release.md | 64 +++++++++++++++++++++++++++++++++ docs/src/how-to-release.md.in | 48 +++++++++++++++++++++++++ 7 files changed, 121 insertions(+), 136 deletions(-) create mode 100644 docs/src/how-to-release.md create mode 100644 docs/src/how-to-release.md.in diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 56081db04..c649bb814 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -108,6 +108,7 @@ nav: - "Auxiliary commands": "reference-main-auxiliary-commands.md" - "Manual page": "manpage.md" - "Building from source": "build.md" + - "How to create a new release": "how-to-release.md" - "Documents for previous releases": "release-docs.md" - "Glossary": "glossary.md" - "What's new in Miller 6": "new-in-miller-6.md" diff --git a/docs/src/build.md b/docs/src/build.md index 499edddcb..e2a6c59f9 100644 --- a/docs/src/build.md +++ b/docs/src/build.md @@ -58,71 +58,3 @@ These are necessary to produce the `mlr` executable. ### Optional external dependencies This documentation pageset is built using [https://www.mkdocs.org/](MkDocs). Please see [https://github.com/johnkerl/miller/blob/main/docs/README.md](https://github.com/johnkerl/miller/blob/main/docs/README.md) for details. - -## Creating a new release: for developers - -This is my checklist for making new releases. - -In this example I am using version 6.1.0 to 6.2.0; of course that will change for subsequent revisions. - -* Update version found in `mlr --version` and `man mlr`: - - * Edit `internal/pkg/version/version.go` from `6.1.0-dev` to `6.2.0`. - * Edit `miller.spec`: `Version`, and `changelog` entry - * Run `make dev` in the Miller repo base directory - * The ordering in this makefile rule is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs. - * Commit and push. - -* Create the release tarball: - - * `make release_tarball` - * This creates `miller-6.2.0.tar.gz` which we'll upload to GitHub, the URL of which will be in our `miller.spec` - * Prepare the source RPM following [README-RPM.md](https://github.com/johnkerl/miller/blob/main/README-RPM.md). - -* Create the Github release tag: - - * Don't forget the `v` in `v6.2.0` - * Write the release notes - * Get binaries from latest successful build from [https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions), or, build them on buildboxes. Note that thanks to [PR 822](https://github.com/johnkerl/miller/pull/822) which introduces [goreleaser](https://github.com/johnkerl/miller/blob/main/.goreleaser.yml) there are versions for many platforms auto-built and auto-attached to the GitHub release (below). The only exception is for Windows: goreleaser makes a `.tar.gz` file but it's nice to attach a `.zip` from GitHub actions for the benefit of Windows users. - * Attach the release tarball, Windows `.zip`, and SRPM. Double-check assets were successfully uploaded. - * Publish the release. Note that gorelease will create and attach the rest of the binaries. - -* Check the release-specific docs: - - * Look at [https://miller.readthedocs.io](https://miller.readthedocs.io) for new-version docs, after a few minutes' propagation time. Note this won't work until Miller 6 is released. - -* Notify: - - * Submit `brew` pull request; notify any other distros which don't appear to have autoupdated since the previous release (notes below) - * Similarly for `macports`: [https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile](https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile) - * See also [README-versions.md](https://github.com/johnkerl/miller/blob/main/README-versions.md) -- distros usually catch up over time but some contacts/pings never hurt to kick-start processes after owners move on from a project they started. - * Social-media updates. - -
-# brew notes:
-git remote add upstream https://github.com/Homebrew/homebrew-core # one-time setup only
-git fetch upstream
-git rebase upstream/master
-git checkout -b miller-6.1.0
-shasum -a 256 /path/to/mlr-6.1.0.tar.gz
-edit Formula/miller.rb
-# Test the URL from the line like
-#   url "https://github.com/johnkerl/miller/releases/download/v6.1.0/mlr-6.1.0.tar.gz"
-# in a browser for typos.
-# A '@BrewTestBot Test this please' comment within the homebrew-core pull request
-# will restart the homebrew travis build.
-git add Formula/miller.rb
-git commit -m 'miller 6.1.0'
-git push -u origin miller-6.1.0
-(submit the pull request)
-
- -* Afterwork: - - * Edit `internal/pkg/version/version.go` to change version from `6.2.0` to `6.2.0-dev`. - * `make dev` - * Commit and push. - -## Misc. development notes - -I use terminal width 120 and tabwidth 4. Miller documents use the Oxford comma: not _red, yellow and green_, but rather _red, yellow, and green_. diff --git a/docs/src/build.md.in b/docs/src/build.md.in index db79eaafd..b01464d20 100644 --- a/docs/src/build.md.in +++ b/docs/src/build.md.in @@ -42,71 +42,3 @@ These are necessary to produce the `mlr` executable. ### Optional external dependencies This documentation pageset is built using [https://www.mkdocs.org/](MkDocs). Please see [https://github.com/johnkerl/miller/blob/main/docs/README.md](https://github.com/johnkerl/miller/blob/main/docs/README.md) for details. - -## Creating a new release: for developers - -This is my checklist for making new releases. - -In this example I am using version 6.1.0 to 6.2.0; of course that will change for subsequent revisions. - -* Update version found in `mlr --version` and `man mlr`: - - * Edit `internal/pkg/version/version.go` from `6.1.0-dev` to `6.2.0`. - * Edit `miller.spec`: `Version`, and `changelog` entry - * Run `make dev` in the Miller repo base directory - * The ordering in this makefile rule is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs. - * Commit and push. - -* Create the release tarball: - - * `make release_tarball` - * This creates `miller-6.2.0.tar.gz` which we'll upload to GitHub, the URL of which will be in our `miller.spec` - * Prepare the source RPM following [README-RPM.md](https://github.com/johnkerl/miller/blob/main/README-RPM.md). - -* Create the Github release tag: - - * Don't forget the `v` in `v6.2.0` - * Write the release notes - * Get binaries from latest successful build from [https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions), or, build them on buildboxes. Note that thanks to [PR 822](https://github.com/johnkerl/miller/pull/822) which introduces [goreleaser](https://github.com/johnkerl/miller/blob/main/.goreleaser.yml) there are versions for many platforms auto-built and auto-attached to the GitHub release (below). The only exception is for Windows: goreleaser makes a `.tar.gz` file but it's nice to attach a `.zip` from GitHub actions for the benefit of Windows users. - * Attach the release tarball, Windows `.zip`, and SRPM. Double-check assets were successfully uploaded. - * Publish the release. Note that gorelease will create and attach the rest of the binaries. - -* Check the release-specific docs: - - * Look at [https://miller.readthedocs.io](https://miller.readthedocs.io) for new-version docs, after a few minutes' propagation time. Note this won't work until Miller 6 is released. - -* Notify: - - * Submit `brew` pull request; notify any other distros which don't appear to have autoupdated since the previous release (notes below) - * Similarly for `macports`: [https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile](https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile) - * See also [README-versions.md](https://github.com/johnkerl/miller/blob/main/README-versions.md) -- distros usually catch up over time but some contacts/pings never hurt to kick-start processes after owners move on from a project they started. - * Social-media updates. - -GENMD-CARDIFY -# brew notes: -git remote add upstream https://github.com/Homebrew/homebrew-core # one-time setup only -git fetch upstream -git rebase upstream/master -git checkout -b miller-6.1.0 -shasum -a 256 /path/to/mlr-6.1.0.tar.gz -edit Formula/miller.rb -# Test the URL from the line like -# url "https://github.com/johnkerl/miller/releases/download/v6.1.0/mlr-6.1.0.tar.gz" -# in a browser for typos. -# A '@BrewTestBot Test this please' comment within the homebrew-core pull request -# will restart the homebrew travis build. -git add Formula/miller.rb -git commit -m 'miller 6.1.0' -git push -u origin miller-6.1.0 -(submit the pull request) -GENMD-EOF - -* Afterwork: - - * Edit `internal/pkg/version/version.go` to change version from `6.2.0` to `6.2.0-dev`. - * `make dev` - * Commit and push. - -## Misc. development notes - -I use terminal width 120 and tabwidth 4. Miller documents use the Oxford comma: not _red, yellow and green_, but rather _red, yellow, and green_. diff --git a/docs/src/contributing.md b/docs/src/contributing.md index 528194f40..ad080150e 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -50,3 +50,7 @@ Much of Miller's documentation is autogenerated from code. With the `miller` dir `$PATH` (so it will find the modified `mlr` executable if you've modified any source code), please do `make dev` in the Miller base directory. This runs source build, unit test, regression test, manual-page autogen, document autogen, and document static-build all in the correct order. + +## Misc. development notes + +Miller code avoids linewraps while using terminal width 120 and tabwidth 4. Miller documents use the Oxford comma: not _red, yellow and green_, but rather _red, yellow, and green_. diff --git a/docs/src/contributing.md.in b/docs/src/contributing.md.in index dae0dddab..cb810e508 100644 --- a/docs/src/contributing.md.in +++ b/docs/src/contributing.md.in @@ -34,3 +34,7 @@ Much of Miller's documentation is autogenerated from code. With the `miller` dir `$PATH` (so it will find the modified `mlr` executable if you've modified any source code), please do `make dev` in the Miller base directory. This runs source build, unit test, regression test, manual-page autogen, document autogen, and document static-build all in the correct order. + +## Misc. development notes + +Miller code avoids linewraps while using terminal width 120 and tabwidth 4. Miller documents use the Oxford comma: not _red, yellow and green_, but rather _red, yellow, and green_. diff --git a/docs/src/how-to-release.md b/docs/src/how-to-release.md new file mode 100644 index 000000000..e512855d8 --- /dev/null +++ b/docs/src/how-to-release.md @@ -0,0 +1,64 @@ + +
+ +Quick links: +  +Flags +  +Verbs +  +Functions +  +Glossary +  +Release docs + +
+# How to create a new release + +This is my checklist for making new releases. + +In this example I am using version 6.2.0 to 6.3.0; of course that will change for subsequent revisions. + +* Update version found in `mlr --version` and `man mlr`: + + * Edit `internal/pkg/version/version.go` from `6.2.0-dev` to `6.3.0`. + * Edit `miller.spec`: `Version`, and `changelog` entry + * Run `make dev` in the Miller repo base directory + * The ordering in this makefile rule is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs. + * Commit and push. + +* Create the release tarball: + + * `make release_tarball` + * This creates `miller-6.3.0.tar.gz` which we'll upload to GitHub, the URL of which will be in our `miller.spec` + * Prepare the source RPM following [README-RPM.md](https://github.com/johnkerl/miller/blob/main/README-RPM.md). + +* Create the Github release tag: + + * Don't forget the `v` in `v6.3.0` + * Write the release notes + * Get binaries from latest successful build from [https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions), or, build them on buildboxes. Note that thanks to [PR 822](https://github.com/johnkerl/miller/pull/822) which introduces [goreleaser](https://github.com/johnkerl/miller/blob/main/.goreleaser.yml) there are versions for many platforms auto-built and auto-attached to the GitHub release (below). The only exception is for Windows: goreleaser makes a `.tar.gz` file but it's nice to attach a `.zip` from GitHub actions for the benefit of Windows users. + * Attach the release tarball, Windows `.zip`, and SRPM. Double-check assets were successfully uploaded. + * Publish the release in draft mode, until all CI jobs finish successfully. Note that gorelease will create and attach the rest of the binaries. + * Then mark the release as public. + +* Check the release-specific docs: + + * Look at [https://miller.readthedocs.io](https://miller.readthedocs.io) for new-version docs, after a few minutes' propagation time. Note this won't work until Miller 6 is released. + +* Notify: + + * Submit `brew` pull request; notify any other distros which don't appear to have autoupdated since the previous release (notes below) + * Similarly for `macports`: [https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile](https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile) + * See also [README-versions.md](https://github.com/johnkerl/miller/blob/main/README-versions.md) -- distros usually catch up over time but some contacts/pings never hurt to kick-start processes after owners move on from a project they started. + * Social-media updates. + * Brew notes: + * [How to submit a version upgrade](https://github.com/Homebrew/homebrew-core/blob/HEAD/CONTRIBUTING.md#to-submit-a-version-upgrade-for-the-foo-formula) + * `brew bump-formula-pr --force --strict miller --url https://github.com/johnkerl/miller/releases/download/v6.2.0/miller-6.2.0.tar.gz --sha256 xxx` with `xxx` from `shasum -a 256 miller-6.2.0.tar.gz`. + +* Afterwork: + + * Edit `internal/pkg/version/version.go` to change version from `6.3.0` to `6.3.0-dev`. + * `make dev` + * Commit and push. diff --git a/docs/src/how-to-release.md.in b/docs/src/how-to-release.md.in new file mode 100644 index 000000000..3168b5dc6 --- /dev/null +++ b/docs/src/how-to-release.md.in @@ -0,0 +1,48 @@ +# How to create a new release + +This is my checklist for making new releases. + +In this example I am using version 6.2.0 to 6.3.0; of course that will change for subsequent revisions. + +* Update version found in `mlr --version` and `man mlr`: + + * Edit `internal/pkg/version/version.go` from `6.2.0-dev` to `6.3.0`. + * Edit `miller.spec`: `Version`, and `changelog` entry + * Run `make dev` in the Miller repo base directory + * The ordering in this makefile rule is important: the first build creates `mlr`; the second runs `mlr` to create `manpage.txt`; the third includes `manpage.txt` into one of its outputs. + * Commit and push. + +* Create the release tarball: + + * `make release_tarball` + * This creates `miller-6.3.0.tar.gz` which we'll upload to GitHub, the URL of which will be in our `miller.spec` + * Prepare the source RPM following [README-RPM.md](https://github.com/johnkerl/miller/blob/main/README-RPM.md). + +* Create the Github release tag: + + * Don't forget the `v` in `v6.3.0` + * Write the release notes + * Get binaries from latest successful build from [https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions), or, build them on buildboxes. Note that thanks to [PR 822](https://github.com/johnkerl/miller/pull/822) which introduces [goreleaser](https://github.com/johnkerl/miller/blob/main/.goreleaser.yml) there are versions for many platforms auto-built and auto-attached to the GitHub release (below). The only exception is for Windows: goreleaser makes a `.tar.gz` file but it's nice to attach a `.zip` from GitHub actions for the benefit of Windows users. + * Attach the release tarball, Windows `.zip`, and SRPM. Double-check assets were successfully uploaded. + * Publish the release in draft mode, until all CI jobs finish successfully. Note that gorelease will create and attach the rest of the binaries. + * Then mark the release as public. + +* Check the release-specific docs: + + * Look at [https://miller.readthedocs.io](https://miller.readthedocs.io) for new-version docs, after a few minutes' propagation time. Note this won't work until Miller 6 is released. + +* Notify: + + * Submit `brew` pull request; notify any other distros which don't appear to have autoupdated since the previous release (notes below) + * Similarly for `macports`: [https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile](https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile) + * See also [README-versions.md](https://github.com/johnkerl/miller/blob/main/README-versions.md) -- distros usually catch up over time but some contacts/pings never hurt to kick-start processes after owners move on from a project they started. + * Social-media updates. + * Brew notes: + * [How to submit a version upgrade](https://github.com/Homebrew/homebrew-core/blob/HEAD/CONTRIBUTING.md#to-submit-a-version-upgrade-for-the-foo-formula) + * `brew bump-formula-pr --force --strict miller --url https://github.com/johnkerl/miller/releases/download/v6.2.0/miller-6.2.0.tar.gz --sha256 xxx` with `xxx` from `shasum -a 256 miller-6.2.0.tar.gz`. + +* Afterwork: + + * Edit `internal/pkg/version/version.go` to change version from `6.3.0` to `6.3.0-dev`. + * `make dev` + * Commit and push.