Mirrors/miller
1
0
Fork 0
mirror of https://github.com/johnkerl/miller.git synced 2026-07-17 16:38:54 +00:00
Code Issues Projects Releases Wiki Activity

Freshen notes on how to create a release

Browse source
This commit is contained in:
John Kerl 2022-03-07 23:38:13 -05:00
parent eb48851455
commit 3903e8059e
7 changed files with 121 additions and 136 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/mkdocs.yml
View file

@ -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"

68
docs/src/build.md
View file

@ -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.
<pre class="pre-non-highlight-non-pair">
# 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)
</pre>
* 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_.

68
docs/src/build.md.in
View file

@ -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_.

4
docs/src/contributing.md
View file

@ -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_.

4
docs/src/contributing.md.in
View file

@ -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_.

64
docs/src/how-to-release.md Normal file
View file

@ -0,0 +1,64 @@
<!--- PLEASE DO NOT EDIT DIRECTLY. EDIT THE .md.in FILE PLEASE. --->
<div>
<span class="quicklinks">
Quick links:
&nbsp;
<a class="quicklink" href="../reference-main-flag-list/index.html">Flags</a>
&nbsp;
<a class="quicklink" href="../reference-verbs/index.html">Verbs</a>
&nbsp;
<a class="quicklink" href="../reference-dsl-builtin-functions/index.html">Functions</a>
&nbsp;
<a class="quicklink" href="../glossary/index.html">Glossary</a>
&nbsp;
<a class="quicklink" href="../release-docs/index.html">Release docs</a>
</span>
</div>
# 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.

48
docs/src/how-to-release.md.in Normal file
View file

@ -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.