Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
proposal: move mature wiki content behind Gerrit #34038
The Go Wiki has over 160 pages, and a set of rules that aren't being followed. There also isn't an effective review process in place, as we explain further below.
I propose that we move the mature content behind Gerrit, to better ensure its quality and maintainability, and so that it can be blessed without fear of uncontrolled edits.
This proposal does not cover what to do with the rest of the wiki content, or what to do with the existing wiki itself. That is left for another proposal to tackle.
It's only possible to have Go's wiki readable or writable by everyone. The Go project opted for anyone to edit them.
This has the advantage that the barrier to entry is low. However, this also means that there's no review process involved, and anyone can create a new wiki page at any time. The main wiki page reads:
However, it doesn't look like the process to add new pages works. With 160 pages, I could only find about a dozen issues requesting the addition of a new wiki page after a five minute search, with queries like
The quality of the pages also varies greatly. Some of them were written or maintained by the Go team, such as CodeReviewComments, Modules, and AssemblyPolicy. These are well reviewed, and are often considered "blessed" by the Go project.
On the other hand, many others have never been approved by a Go issue and have gone through no proper reviews anywhere public. Note that I'm not attaching any examples here to not point any fingers at any wiki authors.
The other side of the problem is that, while the wiki is often cited as being "maintained by the Go community", many Go users treat anything under the
Finally, there is https://groups.google.com/forum/#!forum/golang-wikichanges, but that's a system that requires lots of active attention and ultimately isn't as effective as code review. As an example, the Modules page was deleted on August 26th, so the page was gone until someone noticed and reverted the edit.
Important documentation should go through the review process, just like code and godoc changes do. There's currently no way to do that with GitHub Wikis.
I propose the following steps:
Won't this increase the barrier to entry when contributing to the wiki pages?
Now that GitHub Pull Requests are an option, I think the process would be very similar. GitHub even has a web editor that someone can use on a markdown file to send a PR, without ever using the command line. We could set up the git repository to mirror PRs to Gerrit.
Why a separate git repository?
I think the amount of content wouldn't fit well into the main Go repository. For example, it should be fine for pages to include images, but we don't want those to make the main repository larger. Moreover, we don't want the release process to affect when the pages can be updated.
Who decides what pages should be part of the reviewed git repo?
I think we should start with a small number of pages, like 10; 160 is far too many for us to deal with in the short term. Over time, more pages can be moved to the new repository, if they are important and go through a review. Some pages, like lists of user projects or events, should remain freely editable, as they quickly go out of sync.
A starting point for a list of pages to be moved behind Gerrit:
How do we avoid dead links to
What should we do about existing URLs? We could update the golang.org/wiki redirector, but people may have links to the github.com/golang/go/wiki site. Perhaps we could have the old wiki redirect to the new one.
We want to be careful to keep pages easy to edit and make sure that everything is deployed automatically. One approach we could take is to create a new wiki repo, and permit anybody with +2 access to change it without code review. Non-submitters would require Gerrit review as usual.
I assume the new repo would be a bunch of Markdown files. Should we mirror to GitHub? Or should we rely on Gerrit to present the Markdown format?
Any work we do here should likely wait until #29206 is completed.
I'm not sure; I'm not familiar enough with what's under
We definitely want to keep those working somehow. The FAQ briefly covers this.
That sounds fine to me.
I think we should; many are used to navigating git repositories on GitHub, and we want to allow PRs via GerritBot for those who aren't familiar with Gerrit.
That seems fine. Hopefully that can move forward during this cycle, now that 1.13 is out :)
I want to clarify if this proposal is just about creating a code-review barrier to editing the wiki. If that is the case, wouldn't it be possible to restrict the wiki's editing to collaborators only (mainly just for gopherbot)? We can still have a separate repository that is guarded through Gerrit. After that, all PRs/CLs could go through gerrit, and gopherbot could apply all of the approved changes back on github.
It is already possible to locally clone and edit a github wiki. It is just a directory full of markdown files. This repo's wiki can be cloned as
This way, the original URLs can be preserved, and no redirection is required.
That's an interesting idea. How would PRs to the Wiki work? As far as I know, one can only send PRs to modify the files in a repository itself, and I don't think the Wiki files are part of that. From your
I chatted today with @andybons and @dmitshur (owners of x/website). I think we're in agreement that content displayed on golang.org that does not come from GOROOT should be stored in the x/website repo itself, rather than a third location. As part of #33637, I've been thinking of adding new module documentation there. I'll start moving ahead with those changes soon and adding content there.
I think it's still an open question how we map pages currently on the wiki to golang.org pages. I generally agree we should do that though.
peripheral to this topic
but might the order of authenticity for textual content on a wiki page be specified as
A) golang go and golang sub-repo executables' output, e.g.,
B) the html pages' content from doc, pkg, ref
C) the html pages' content from blog and tour
were there unanimity among Chinese, Japanese, and Korean Go coders
that in the lower left margin of a given wiki page would appear "◎ Contributor name"
indicating not to edit that page unless you are a Contributor, I'd accept thus using
obviously this should be explained on the wiki Home page