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

proposal: move mature wiki content behind Gerrit #34038

Open
mvdan opened this issue Sep 3, 2019 · 13 comments
Open

proposal: move mature wiki content behind Gerrit #34038

mvdan opened this issue Sep 3, 2019 · 13 comments

Comments

@mvdan
Copy link
Member

@mvdan mvdan commented Sep 3, 2019

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 mvdan added this to the Proposal milestone Sep 3, 2019
@mvdan

This comment has been minimized.

Copy link
Member Author

@mvdan mvdan commented Sep 3, 2019

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:

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

This comment has been minimized.

Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Sep 3, 2019

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

This comment has been minimized.

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 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

This comment has been minimized.

Copy link
Member

@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 https://github.com/golang/go.wiki.git

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

@mvdan

This comment has been minimized.

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.

@smasher164

This comment has been minimized.

Copy link
Member

@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.

@jayconrod

This comment has been minimized.

Copy link
Contributor

@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 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

This comment has been minimized.

Copy link
Contributor

@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
@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Oct 25, 2019

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., go help c

B) the html pages' content from doc, pkg, ref

C) the html pages' content from blog and tour

@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Oct 26, 2019

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

@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Oct 26, 2019

were the preceding comment's proposal accepted

an auto Revert could be coded with a warning notice e-mailed to any violating GitHub account holder

@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Oct 26, 2019

Having edited the Modules page, I don't mind the restriction inferred from my "alternate" proposal.

@oiooj
@knsh14
@kucuny

Would you care to chip in on the "alternate" proposal?

@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Dec 2, 2019

My "alternate" proposal doesn't seem to be getting much traction.

I'm a bit reluctant to refer new Golang coders to a wiki page as being authoritative where presently any community member can edit those pages.

#35919 (comment)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.