Tidy up README.md
#290
Tidy up README.md
#290
Conversation
* Create a new section explicitly describing the installation process. * Add the definition of a `go_toolchain` to the installation instructions. * Drop dangling reference to (the now-deprecated) `go_get`. * Drop the warning at the end of the document about how a Go toolchain is required for Go 1.20+ (which everyone ought to be using by now, given that 1.20 fell out of support upstream some time ago). * Some other minor formatting and wording improvements.
chrisnovakovic
added
the
documentation
| ```python | ||
| plugin_repo( | ||
| name = "go", | ||
| revision="vx.x.x", | ||
| revision = "vx.x.x", # A go-rules version |
There was a problem hiding this comment.
Where should the reader find which version to use?
|
|
||
| # Installation | ||
|
|
||
| First, add the plugin to your Please repo. In `plugins/BUILD`: |
There was a problem hiding this comment.
It isn't strictly required that it be plugins/BUILD; can we rephrase this?
| [Plugin "go"] | ||
| Target = //plugins:go | ||
| GoTool = //third_party/go:toolchain|go |
There was a problem hiding this comment.
Do we need to add Stdlib here?
| Go is especially suited to writing command line tools and utilities. Binaries can be run with `plz run`, or used | ||
| as tools for [custom rules](https://please.build/codelabs/genrule/#0). | ||
|
|
||
| # Installation |
There was a problem hiding this comment.
Can we just recommend using plz init plugin go here? (and maybe leave the manual process as an appendix)
| Next, define a version of Go for the plugin to use. In `third_party/go/BUILD`: | ||
|
|
||
| ```python | ||
| subinclude("///go//build_defs:go") |
There was a problem hiding this comment.
Should we recommend
[parse]
preloadsubincludes = ///go//build_defs:go
(plz plugin init sets this up)
There was a problem hiding this comment.
Agreed.
The phases of plz initialization and implicit actions are barriers to entry. Documentation should put users on the happy path/path of least resistance, not the path of maximal detail. The detail needs to be explained someplace, but it shouldn't be in the readmes that get things up to speed for a user. If people want to see what changed, git diff should be sufficient to see what happens when someone runs plz plugin init go, or whatever. $0.02.
| ) | ||
| ``` | ||
|
|
||
| Introduce dependencies on third-party Go modules with `go_repo`: |
There was a problem hiding this comment.
Worth a reference to puku here?
There was a problem hiding this comment.
Worth doing, but puku is not quite my friend yet: I still routinely fall back to go_module and find myself fighting puku sync with some degree of regularity. The idealized end-to-end workflow for "day in the life of an engineer using a repo with plz" isn't well defined and requires a fair amount of digging.
go_toolchainto the installation instructions.go_get.