move mature wiki content behind Gerrit

[mvdan]

Summary

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.

Problem statement

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:

• This wiki is open to editing by any member of the Go community with a GitHub account.
• If you would like to add a new page, please first open an issue in the Go issue tracker [...].
• [...] please open an issue before renaming or removing any wiki page.

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 is:issue wiki page in:title.

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 golang/go repository as being blessed by the Go team. This is an understandable misconception, as the repository is otherwise under the team's supervision.

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.

Proposed solution

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:

1. Announce the plan below to golang-dev and golang-nuts, and update the main wiki page
2. Gradually move relevant wiki pages somewhere under Gerrit, such as an x/doc or x/wiki repository
3. Start making these pages available somewhere official, such as under golang.org/doc or golang.org/wiki
4. Modify the moved Wiki pages to link or redirect to their new locations

[mvdan]

FAQs

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:

• Modules - see doc: restructure module documentation #33637
• CodeReviewComments
• CommitMessage
• Gardening
• NoPlusOne
• Go-Release-Cycle

How do we avoid dead links to golang/go/wiki?

Unfortunately, I can't find any official GitHub source on how to do wiki page redirects. We could do manual ones, with content along the lines of:

This page has moved to https://golang.org/doc/SomePage.
To contribute, see https://github.com/golang/doc.

On the plus side, golang.org/wiki/SomePage already redirects to the GitHub wiki, so we could make it smart enough not to do that for the pages moved off of the public wiki.

[ianlancetaylor]

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.

[mvdan]

What should we do about existing URLs?

I'm not sure; I'm not familiar enough with what's under golang.org to decide here.

people may have links to the github.com/golang/go/wiki site

We definitely want to keep those working somehow. The FAQ briefly covers this.

permit anybody with +2 access to change it without code review.

That sounds fine to me.

Should we mirror to GitHub?

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.

Any work we do here should likely wait until #29206 is completed.

That seems fine. Hopefully that can move forward during this cycle, now that 1.13 is out :)

[smasher164]

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

git clone https://github.com/golang/go.wiki.git

This way, the original URLs can be preserved, and no redirection is required.

[mvdan]

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 git clone line, it seems like a separate repository altogether.

[smasher164]

You're right in that there would have to be a separate repository. However, modifying files (specifically the wiki) on the repo can be done via push/commit as well. My idea was that gopherbot would mirror the commits to the github repo's wiki.

[jayconrod]

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.

[dgryski]

Addition to the list of pages to move: #34384

[mvdan]

Could we move this proposal to being accepted? It seems like we all agree that this should happen, and the thread has mostly been stuck on the details of not breaking links to existing wiki pages. I think my suggestion at the end of #34038 (comment) is still reasonable, and we could eventually remove the wiki pages entirely, say in two or three years.

[rsc]

This doesn't really have to go through the proposal process. There is a long-term plan to do just this. We're just not there yet. Happy to mark accepted.

[rsc]

Now a duplicate of #61940.