mirror of
https://github.com/johnkerl/miller.git
synced 2026-07-17 16:38:54 +00:00
CONTRIBUTING.md
This commit is contained in:
John Kerl
parent
d008b70a1b
commit
8ae20589eb
4 changed files with 114 additions and 44 deletions
81
CONTRIBUTING.md
Normal file
81
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# Contributing to Miller
|
||||
|
||||
Thanks for your interest in contributing! This page is a quick-start guide for code, test, and
|
||||
documentation contributions. It links out to more detailed docs rather than repeating them, so if
|
||||
something below feels thin, follow the link.
|
||||
|
||||
## Asking questions / reporting issues
|
||||
|
||||
* Questions and general discussion: [GitHub Discussions](https://github.com/johnkerl/miller/discussions)
|
||||
* Bug reports and feature requests: [GitHub Issues](https://github.com/johnkerl/miller/issues)
|
||||
* See also [notes on issue-labeling](https://github.com/johnkerl/miller/wiki/Issue-labeling).
|
||||
|
||||
When filing a bug, please include your Miller version (`mlr --version`), OS, and a minimal repro
|
||||
(command line plus a few lines of sample input).
|
||||
|
||||
## Getting the source and building
|
||||
|
||||
```
|
||||
git clone https://github.com/johnkerl/miller
|
||||
cd miller
|
||||
make # builds ./mlr
|
||||
make check # runs unit + regression tests
|
||||
```
|
||||
|
||||
Miller is written in Go (1.25+ as of July 2026) with no non-standard-library runtime dependencies.
|
||||
For build details beyond `make`/`go build`, see the [Building from
|
||||
source](https://miller.readthedocs.io/en/latest/build) doc and [README-dev.md](./README-dev.md).
|
||||
|
||||
## Before opening a PR
|
||||
|
||||
Run the full developer workflow:
|
||||
|
||||
```
|
||||
make dev
|
||||
```
|
||||
|
||||
This formats code, builds, runs unit and regression tests, and regenerates
|
||||
docs/man-pages, in the right order. A PR that passes this is in good shape to
|
||||
submit.
|
||||
|
||||
A few conventions to follow:
|
||||
|
||||
* Code should read like idiomatic, `go fmt`-clean Go. Miller favors clarity
|
||||
over cleverness, including some acceptable code duplication: see
|
||||
[README-dev.md: Source-code goals](./README-dev.md#source-code-goals).
|
||||
* Avoid line wraps at a terminal width of 120 columns, tabwidth 4.
|
||||
* Prose in docs/comments uses the Oxford comma.
|
||||
* Reference relevant issue numbers in commit messages where applicable.
|
||||
|
||||
## Where to look depending on what you're changing
|
||||
|
||||
* **Adding or fixing a built-in DSL function**: implement in `pkg/bifs/`,
|
||||
add unit tests alongside, update `docs/src/`.
|
||||
* **Adding/changing a verb (transformer)**: see `pkg/transformers/` and the
|
||||
directory-structure notes in [README-dev.md](./README-dev.md).
|
||||
* **Anything touching the DSL grammar** (`pkg/parsing/mlr.bnf`): see
|
||||
[README-dev.md](./README-dev.md) for the `tools/build-dsl` regeneration step.
|
||||
* **Tests**: Miller's test suite is mostly scripted CLI invocations compared
|
||||
against expected output, plus a smaller set of Go unit tests. See
|
||||
[test/README.md](./test/README.md) for how to run and add cases.
|
||||
* **Documentation**: the published docs are generated from `docs/src/*.md.in`
|
||||
files, not hand-edited `.md`. See [README-docs.md](./README-docs.md) for the
|
||||
edit/preview/build loop.
|
||||
* **Performance work**: see [README-profiling.md](./README-profiling.md) for
|
||||
profiling Miller itself, and [scripts/perf/README.md](./scripts/perf/README.md)
|
||||
for the benchmark scripts used to produce the performance graphs in the docs.
|
||||
* **Background on the Go port** (history, design rationale, why Go over C):
|
||||
see [README-go-port.md](./README-go-port.md). Not required reading to
|
||||
contribute, but useful context for anything touching core internals like
|
||||
`Mlrval` or the record-stream architecture.
|
||||
|
||||
## Using an AI coding assistant
|
||||
|
||||
If you're using Claude Code against this repo, [CLAUDE.md](./CLAUDE.md) has
|
||||
build/test commands and conventions written for that workflow. It's a
|
||||
supplement for AI-assisted contributions, not a replacement for this page.
|
||||
|
||||
## License
|
||||
|
||||
Miller is licensed under the [two-clause BSD license](./LICENSE.txt).
|
||||
Contributions are accepted under the same license.
|
||||
|
|
@ -16,41 +16,33 @@ Quick links:
|
|||
</div>
|
||||
# How to contribute
|
||||
|
||||
## Community
|
||||
## Community discussions
|
||||
|
||||
You can ask questions -- or answer them! -- following the links on the [Community](community.md) page.
|
||||
|
||||
## Documentation improvements
|
||||
|
||||
Pre-release Miller documentation is at [https://github.com/johnkerl/miller/tree/main/docs](https://github.com/johnkerl/miller/tree/main/docs).
|
||||
Pre-release Miller documentation is at
|
||||
[https://github.com/johnkerl/miller/tree/main/docs](https://github.com/johnkerl/miller/tree/main/docs).
|
||||
|
||||
Instructions for modifying, viewing, and submitting PRs for these are in [README-docs.md](https://github.com/johnkerl/miller/blob/main/README-docs.md).
|
||||
|
||||
Once PRs are merged, readthedocs creates [https://miller.readthedocs.io](https://miller.readthedocs.io) using the following configs:
|
||||
Once PRs are merged, readthedocs creates
|
||||
[https://miller.readthedocs.io](https://miller.readthedocs.io) using the following configs:
|
||||
|
||||
* [https://readthedocs.org/projects/miller](https://readthedocs.org/projects/miller)
|
||||
* [https://readthedocs.org/projects/miller/builds](https://readthedocs.org/projects/miller/builds)
|
||||
* [https://github.com/johnkerl/miller/settings/hooks](https://github.com/johnkerl/miller/settings/hooks)
|
||||
|
||||
## Testing
|
||||
## Testing a development build
|
||||
|
||||
As of Miller-6's current pre-release status, the best way to test is to either build from source via [Building from source](build.md), or by getting a recent binary at [https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions), then click latest build, then *Artifacts*. Then simply use Miller for whatever you do, and create an issue at [https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues).
|
||||
To try out unreleased changes, either build from source via [Building from source](build.md), or
|
||||
grab a recent binary from
|
||||
[https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions) (latest
|
||||
build → *Artifacts*). Then use it as you normally would, and file an issue at
|
||||
[https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues) if you hit
|
||||
something.
|
||||
|
||||
## Feature development
|
||||
## Source-code mods
|
||||
|
||||
Issues: [https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues)
|
||||
|
||||
Developer notes: [https://github.com/johnkerl/miller/blob/main/README-dev.md](https://github.com/johnkerl/miller/blob/main/README-dev.md)
|
||||
|
||||
PRs which pass regression test ([https://github.com/johnkerl/miller/blob/main/test/README.md](https://github.com/johnkerl/miller/blob/main/test/README.md)) are always welcome!
|
||||
|
||||
## Build script
|
||||
|
||||
Much of Miller's documentation is autogenerated from code. With the `miller` directory in your
|
||||
`$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_.
|
||||
Please see the repo's [CONTRIBUTING.md](https://github.com/johnkerl/miller/blob/main/CONTRIBUTING.md).
|
||||
|
|
|
|||
|
|
@ -1,40 +1,32 @@
|
|||
# How to contribute
|
||||
|
||||
## Community
|
||||
## Community discussions
|
||||
|
||||
You can ask questions -- or answer them! -- following the links on the [Community](community.md) page.
|
||||
|
||||
## Documentation improvements
|
||||
|
||||
Pre-release Miller documentation is at [https://github.com/johnkerl/miller/tree/main/docs](https://github.com/johnkerl/miller/tree/main/docs).
|
||||
Pre-release Miller documentation is at
|
||||
[https://github.com/johnkerl/miller/tree/main/docs](https://github.com/johnkerl/miller/tree/main/docs).
|
||||
|
||||
Instructions for modifying, viewing, and submitting PRs for these are in [README-docs.md](https://github.com/johnkerl/miller/blob/main/README-docs.md).
|
||||
|
||||
Once PRs are merged, readthedocs creates [https://miller.readthedocs.io](https://miller.readthedocs.io) using the following configs:
|
||||
Once PRs are merged, readthedocs creates
|
||||
[https://miller.readthedocs.io](https://miller.readthedocs.io) using the following configs:
|
||||
|
||||
* [https://readthedocs.org/projects/miller](https://readthedocs.org/projects/miller)
|
||||
* [https://readthedocs.org/projects/miller/builds](https://readthedocs.org/projects/miller/builds)
|
||||
* [https://github.com/johnkerl/miller/settings/hooks](https://github.com/johnkerl/miller/settings/hooks)
|
||||
|
||||
## Testing
|
||||
## Testing a development build
|
||||
|
||||
As of Miller-6's current pre-release status, the best way to test is to either build from source via [Building from source](build.md), or by getting a recent binary at [https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions), then click latest build, then *Artifacts*. Then simply use Miller for whatever you do, and create an issue at [https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues).
|
||||
To try out unreleased changes, either build from source via [Building from source](build.md), or
|
||||
grab a recent binary from
|
||||
[https://github.com/johnkerl/miller/actions](https://github.com/johnkerl/miller/actions) (latest
|
||||
build → *Artifacts*). Then use it as you normally would, and file an issue at
|
||||
[https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues) if you hit
|
||||
something.
|
||||
|
||||
## Feature development
|
||||
## Source-code mods
|
||||
|
||||
Issues: [https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues)
|
||||
|
||||
Developer notes: [https://github.com/johnkerl/miller/blob/main/README-dev.md](https://github.com/johnkerl/miller/blob/main/README-dev.md)
|
||||
|
||||
PRs which pass regression test ([https://github.com/johnkerl/miller/blob/main/test/README.md](https://github.com/johnkerl/miller/blob/main/test/README.md)) are always welcome!
|
||||
|
||||
## Build script
|
||||
|
||||
Much of Miller's documentation is autogenerated from code. With the `miller` directory in your
|
||||
`$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_.
|
||||
Please see the repo's [CONTRIBUTING.md](https://github.com/johnkerl/miller/blob/main/CONTRIBUTING.md).
|
||||
|
|
|
|||
|
|
@ -30,8 +30,12 @@ Much of the mechanical work below is automated by `tools/release.sh`, which has
|
|||
|
||||
`rpmbuild` is mandatory for `pre-release` (the SRPM is a required release artifact); `rpmlint` is optional and is run only if installed. The ReadTheDocs admin steps and the flip from pre-release to public remain manual. Each subcommand is idempotent, so a partial run can be re-invoked safely.
|
||||
|
||||
**If you are running `pre-release`, do not also do the version-bump / tarball / SRPM / GitHub-release-and-tag steps below by hand first.** `pre-release` does all of that itself, in the order that makes the tag land correctly (version bump commit pushed *before* the tag is cut). Manually creating the GitHub release/tag before the version-bump commit is pushed reproduces the exact bug called out under "Create the GitHub release tag" below -- the tag gets pinned to whatever commit `main` was at that moment, forever, even though it looks like `--target main`. Worse, `pre-release`'s idempotency check only confirms *a* release exists for the tag; it does not verify the tagged commit actually contains the version bump, so a subsequent `pre-release` run will not notice or fix a bad tag -- it will just keep uploading assets to it. If this happens, the only fix is to delete the GitHub release and the tag (`git push --delete origin vX.Y.Z`, plus the local tag) and recreate it pointing at the correct commit.
|
||||
|
||||
## Manual steps
|
||||
|
||||
These are the individual steps `pre-release`/`docs`/`afterwork` automate, kept here as a reference for what each phase actually does (and as a fallback if you need to run a step by hand). Do not run these separately from the script for a release the script is also handling.
|
||||
|
||||
* Update version found in `mlr --version` and `man mlr`:
|
||||
|
||||
* Edit `pkg/version/version.go` from `6.2.0-dev` to `6.3.0`.
|
||||
|
|
@ -54,6 +58,7 @@ Much of the mechanical work below is automated by `tools/release.sh`, which has
|
|||
|
||||
* Create the GitHub release tag:
|
||||
|
||||
* If `pre-release` is handling this release, skip this step -- do not create the release/tag by hand first. See the warning above.
|
||||
* Don't forget the `v` in `v6.3.0`
|
||||
* Write the release notes -- save as a pre-release until below
|
||||
* Be sure the commit being used is the (non-`main`) PR commit containing the new version, or, `main` after that PR is merged back to `main`. (Otherwise, the release will be tagging the commit _before_ the changes, and `mlr version` will not show the new release number.)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue