Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

move mature wiki content behind Gerrit #34038

mvdan opened this issue Sep 3, 2019 · 10 comments

move mature wiki content behind Gerrit #34038

mvdan opened this issue Sep 3, 2019 · 10 comments


Copy link

@mvdan mvdan commented Sep 3, 2019


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!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 or
  4. Modify the moved Wiki pages to link or redirect to their new locations
@mvdan mvdan added this to the Proposal milestone Sep 3, 2019
Copy link
Member Author

@mvdan mvdan commented Sep 3, 2019


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 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
To contribute, see

On the plus side, 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.

Copy link

@ianlancetaylor ianlancetaylor commented Sep 3, 2019

What should we do about existing URLs? We could update the redirector, but people may have links to the 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.

Copy link
Member Author

@mvdan mvdan commented Sep 8, 2019

What should we do about existing URLs?

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

people may have links to the 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 :)

Copy link

@smasher164 smasher164 commented Sep 8, 2019

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

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

Copy link
Member Author

@mvdan mvdan commented Sep 9, 2019

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.

Copy link

@smasher164 smasher164 commented Sep 9, 2019

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.

Copy link

@jayconrod jayconrod commented Sep 19, 2019

I chatted today with @andybons and @dmitshur (owners of x/website). I think we're in agreement that content displayed on 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 pages. I generally agree we should do that though.

Copy link

@dgryski dgryski commented Sep 20, 2019

Addition to the list of pages to move: #34384

@andybons andybons changed the title Proposal: move mature wiki content behind Gerrit proposal: move mature wiki content behind Gerrit Sep 20, 2019
Copy link
Member Author

@mvdan mvdan commented Nov 17, 2020

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.

@ianlancetaylor ianlancetaylor added this to Incoming in Proposals Nov 18, 2020
Copy link

@rsc rsc commented Nov 18, 2020

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 rsc moved this from Incoming to Accepted in Proposals Nov 18, 2020
@rsc rsc changed the title proposal: move mature wiki content behind Gerrit move mature wiki content behind Gerrit Nov 19, 2020
@rsc rsc removed this from the Proposal milestone Nov 19, 2020
@rsc rsc added this to the Backlog milestone Nov 19, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants