README.md Generation Issue

[rwjblue-glean]

Problem Statement

Right now in the repo we have internal/readme/ which has a small Makefile that is used to generate the top level README.md. It seems like the goal here is to ensure that the code snippets stay in sync across changes to the repo (which makes total sense!).

Unfortunately, it's super easy for folks to just throw PRs that target the top level README.md and then we end up in an out of sync situation.

Proposed Solution

Add CI automation to ensure that make in internal/readme/ results in "no changes". This would ensure that anyone that updates the top level README.md is guided towards updating internal/readme/README.src.md, and anyone that updates internal/readme/README.src.md is guided to running make to regenerate the top level with their changes.

Additionally, update CONTRIBUTING.md to have steps to update README.md documented.

Alternatives

If the internal/readme/ package isn't desired anymore, we can just remove it?

[rwjblue-glean]

I'm happy to work on implementing this (and bringing over any changes that have been made to the top level README.md and not to internal/readme/README.src.md), if that seems worthwhile to folks.

[findleyr]

CC @jba

Thanks, I was just thinking about this problem, since we ran into a sync issue yesterday.

The typical way we do this is to have a test that compares the bits, and then use go:generate go test -run=TestGenerateREADME -write. See this for example: https://cs.opensource.google/go/go/+/master:src/go/types/generate_test.go;l=26

The reason we can't do this here is that we're use weave from the x/example project, which is an external dependency that we don't want to add. I think there are two options:

1. Avoid weave, and just roll a quick-and-dirty source code transclusion solution, that is at least testable.
2. Drop the README generation altogether.
3. Do something in CI.

I think the generation has value, because it's all too easy to forget to update README when APIs change. That will be less of an issue as the API stabilizes.

[rwjblue-glean]

I implemented a basic solution over in #53, we can probably do more if you want (e.g. we could auto-rerun weave and push a commit) but this is probably a good start and we can see where things go from there.