readme: provide more context on maintainers and give a testscript overview with links

rogpeppe / go-internal

Selected Go-internal packages factored out from the standard library

BSD 3-Clause "New" or "Revised" License

823 stars 67 forks source link

readme: provide more context on maintainers and give a testscript overview with links #225

Closed thepudds closed 1 year ago

thepudds commented 1 year ago

Help give some context for people who might be evaluating using this repo and are wondering things like:

what is the bus factor for the repo?
who are the maintainers?
are the maintainer(s) of this repo still interested in this repo (including, are they still using it)?
are other people using testscript?
where did testscript come from?

Obviously, someone can hunt around to determine many of these things on their own, but intent is to help make that process more efficient.

Updates #196

bitfield commented 1 year ago

It's worth knowing that the Links header is special: it causes any listed links to be shown in the right-hand pane on pkg.go.dev.

thepudds commented 1 year ago

Hi @bitfield 👋

It's worth knowing that the Links header https://github.com/golang/go/issues/42968: it causes any listed links to be shown in the right-hand pane on pkg.go.dev.

Ah, interesting, TIL.

I guess I don't know how often people are browsing the root https://pkg.go.dev/github.com/rogpeppe/go-internal on pkg.go.dev (vs. browsing API for an importable package), and I guess the "Links" link in the right-hand pane hasn't been jumping out to me personally.

My thought was to put the link in a sentence along with words like "introduction" and "nice" and "series" to encourage interested people to click, but I don't have a strong opinion.

As the target of said link, any preference regarding which form to use?

ldemailly commented 1 year ago

I tested with https://github.com/fortio/testscript/blob/v0.3.1/README.md and you can use ## for links so it's smaller when looking on github and yet still on pkg.go.dev (and I guess probably ### or #### would also work)

mvdan commented 1 year ago

SGTM :) Perhaps worth making a mention that testscript and txtar were both originally written by Russ. We don't want to give the impression that we came up with the idea.

thepudds commented 1 year ago

Thanks for the quick feedback! I think I addressed your comments.

PTAL.

ldemailly commented 1 year ago

You don't want to keep/add back ### Links for pkg.go.dev?