From ba349fe66f1b7a6249c979480c5fd80a31f554d2 Mon Sep 17 00:00:00 2001 From: John Kerl Date: Tue, 12 Jul 2022 17:15:06 -0400 Subject: [PATCH] README-go-port.md -> README-dev.md --- README-go-port.md => README-dev.md | 35 ++++++++---------------------- README-profiling.md | 2 +- README.md | 7 +++++- docs/src/contributing.md | 2 +- docs/src/contributing.md.in | 2 +- docs/src/new-in-miller-6.md | 2 +- docs/src/new-in-miller-6.md.in | 2 +- internal/pkg/README.md | 2 +- 8 files changed, 21 insertions(+), 33 deletions(-) rename README-go-port.md => README-dev.md (96%) diff --git a/README-go-port.md b/README-dev.md similarity index 96% rename from README-go-port.md rename to README-dev.md index b3522e707..48e6fefe3 100644 --- a/README-go-port.md +++ b/README-dev.md @@ -1,10 +1,14 @@ -# Scope - -This note is for a developer point of view. For a user point of view, please see [https://miller.readthedocs.io/en/latest/new-in-miller-6](https://miller.readthedocs.io/en/latest/new-in-miller-6). - # Quickstart for developers -See `makefile` in the repo base directory. +* `make`, `make check`, `make docs`, etc: see [Makefile](Makefile) in the repo base directory. +* Software-testing methodology: see [./test/README.md](./test/README.md). +* Source-code indexing: please see [https://sourcegraph.com/github.com/johnkerl/miller](https://sourcegraph.com/github.com/johnkerl/miller) +* Godoc As of September 2021, `godoc` support is minimal: package-level synopses exist; most `func`/`const`/etc content lacks `godoc`-style comments. To view doc material, you can: + * `go get golang.org/x/tools/cmd/godoc` + * `cd go` + * `godoc -http=:6060 -goroot .` + * Browse to `http://localhost:6060` + * Note: control-C and restart the server, then reload in the browser, to pick up edits to source files # Continuous integration @@ -180,24 +184,3 @@ In summary: * #779 was a bit more involved, and reveals that Go's elegant goroutine/channel processing model comes with the caveat that channelized data should not be organized in many, small pieces. * #809 was also bit more involved, and reveals that library functions are convenient, but profiling and analysis can sometimes reveal an opportunity for an impact, custom solution. * #786 was a massive refactor involving about 10KLOC -- in hindsight it would have been best to do this work at the start of the Go port, not at the end. - -## Software-testing methodology - -See [./test/README.md](./test/README.md). - -## Godoc - -As of September 2021, `godoc` support is minimal: package-level synopses exist; -most `func`/`const`/etc content lacks `godoc`-style comments. - -To view doc material, you can: - -* `go get golang.org/x/tools/cmd/godoc` -* `cd go` -* `godoc -http=:6060 -goroot .` -* Browse to `http://localhost:6060` -* Note: control-C and restart the server, then reload in the browser, to pick up edits to source files - -## Source-code indexing - -Please see https://sourcegraph.com/github.com/johnkerl/miller diff --git a/README-profiling.md b/README-profiling.md index 6f5673961..f546e6609 100644 --- a/README-profiling.md +++ b/README-profiling.md @@ -1,6 +1,6 @@ # See also -* [https://github.com/johnkerl/miller/blob/readme-profiling/README-go-port.md#performance-optimizations](https://github.com/johnkerl/miller/blob/readme-profiling/README-go-port.md#performance-optimizations) +* [https://github.com/johnkerl/miller/blob/readme-profiling/README-dev.md#performance-optimizations](https://github.com/johnkerl/miller/blob/readme-profiling/README-dev.md#performance-optimizations) * [https://miller.readthedocs.io/en/latest/new-in-miller-6/#performance-benchmarks](https://miller.readthedocs.io/en/latest/new-in-miller-6/#performance-benchmarks). * `make bench` to run Go benchmarks for Miller diff --git a/README.md b/README.md index d2f3d4e1f..45838a316 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,12 @@ See also [building from source](https://miller.readthedocs.io/en/latest/build.ht * To run tests: `go test github.com/johnkerl/miller/internal/pkg/...` and `mlr regtest`. * To install: `go install github.com/johnkerl/miller/cmd/mlr` will install to _GOPATH_`/bin/mlr`. * See also the doc page on [building from source](https://miller.readthedocs.io/en/latest/build). -* For more developer information please see [README-go-port.md](./README-go-port.md). +* For more developer information please see [README-dev.md](./README-dev.md). + +# For developers + +* [README-dev.md](README-dev.md) +* [How to contribute](https://miller.readthedocs.io/en/latest/contributing/) # License diff --git a/docs/src/contributing.md b/docs/src/contributing.md index ad080150e..5b988fb19 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -40,7 +40,7 @@ As of Miller-6's current pre-release status, the best way to test is to either b Issues: [https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues) -Developer notes: [https://github.com/johnkerl/miller/blob/main/README-go-port.md](https://github.com/johnkerl/miller/blob/main/README-go-port.md) +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! diff --git a/docs/src/contributing.md.in b/docs/src/contributing.md.in index cb810e508..4a75f993f 100644 --- a/docs/src/contributing.md.in +++ b/docs/src/contributing.md.in @@ -24,7 +24,7 @@ As of Miller-6's current pre-release status, the best way to test is to either b Issues: [https://github.com/johnkerl/miller/issues](https://github.com/johnkerl/miller/issues) -Developer notes: [https://github.com/johnkerl/miller/blob/main/README-go-port.md](https://github.com/johnkerl/miller/blob/main/README-go-port.md) +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! diff --git a/docs/src/new-in-miller-6.md b/docs/src/new-in-miller-6.md index f9088d5f3..e0cbbbe9c 100644 --- a/docs/src/new-in-miller-6.md +++ b/docs/src/new-in-miller-6.md @@ -345,7 +345,7 @@ for more information. ## Developer-specific aspects -* Miller has been ported from C to Go. Developer notes: [https://github.com/johnkerl/miller/blob/main/README-go-port.md](https://github.com/johnkerl/miller/blob/main/README-go-port.md). +* Miller has been ported from C to Go. Developer notes: [https://github.com/johnkerl/miller/blob/main/README-dev.md](https://github.com/johnkerl/miller/blob/main/README-dev.md). * Regression testing has been completely reworked, including regression-testing now running fully on Windows (alongside Linux and Mac) [on each GitHub commit](https://github.com/johnkerl/miller/actions). ## Performance benchmarks diff --git a/docs/src/new-in-miller-6.md.in b/docs/src/new-in-miller-6.md.in index c163970ed..cae4192db 100644 --- a/docs/src/new-in-miller-6.md.in +++ b/docs/src/new-in-miller-6.md.in @@ -294,7 +294,7 @@ for more information. ## Developer-specific aspects -* Miller has been ported from C to Go. Developer notes: [https://github.com/johnkerl/miller/blob/main/README-go-port.md](https://github.com/johnkerl/miller/blob/main/README-go-port.md). +* Miller has been ported from C to Go. Developer notes: [https://github.com/johnkerl/miller/blob/main/README-dev.md](https://github.com/johnkerl/miller/blob/main/README-dev.md). * Regression testing has been completely reworked, including regression-testing now running fully on Windows (alongside Linux and Mac) [on each GitHub commit](https://github.com/johnkerl/miller/actions). ## Performance benchmarks diff --git a/internal/pkg/README.md b/internal/pkg/README.md index ceed8af83..828973c04 100644 --- a/internal/pkg/README.md +++ b/internal/pkg/README.md @@ -1 +1 @@ -Please see [../../README-go-port.md](../../README-go-port.md) for an overview; please see each subdirectory for details about it. +Please see [../../README-dev.md](../../README-dev.md) for an overview; please see each subdirectory for details about it.