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

x/website: add Gerrit basic tutorial in contributing guideines #60397

Open
dolmen opened this issue May 24, 2023 · 2 comments
Open

x/website: add Gerrit basic tutorial in contributing guideines #60397

dolmen opened this issue May 24, 2023 · 2 comments
Labels
Documentation FeatureRequest NeedsFix The path to resolution is known, but the work has not been done. website

Comments

@dolmen
Copy link
Contributor

dolmen commented May 24, 2023

This is about https://go.dev/doc/contribute#review

As long time Open Source contributor and heavy GitHub user, I struggle with the contribution process for Go because of the Gerrit workflow and UI. The Gerrit UI and process is very different from GitHub. For example, I got patches stuck for weeks just because the answers to reviews I had written were just drafts and not sent to the reviewer.

So it would very helpful to add:

  • some basic tutorial for the contributor point of view, with screenshots:
    • how to reply to comment
    • the workflow state schema
    • what to do when a patch in "Your turn" state
  • links to a Gerrit UI onboarding

This presentation seems to have good in-depth content, but goes too deep for someone who just want to send one patch to the Go project.
https://docs.google.com/presentation/d/1C73UgQdzZDw0gzpaEqIC6SPujZJhqamyqO1XOHjH-uk/edit#slide=id.g4d6c16487b_31_60

@gopherbot gopherbot added this to the Unreleased milestone May 24, 2023
@dmitshur
Copy link
Contributor

It's worth taking into account that Gerrit itself has fairly thorough documentation (e.g., see https://gerrit-review.googlesource.com/Documentation/index.html).

For example, https://gerrit-review.googlesource.com/Documentation/user-attention-set.html explains the "Attention Set" feature in depth, and https://gerrit-review.googlesource.com/Documentation/user-review-ui.html goes over all the UI elements that can be useful during code review.

The https://go.dev/doc/contribute#sending_a_change_gerrit section currently explains step by step what it takes to send a change via Gerrit, but it can't cover everything Gerrit offers without also becoming as large as the links I shared above. Gerrit itself is improving and sometimes gets new features (e.g., Attention Set was only added in recent years).

The point I want to make with this is that it could work well to take advantage of Gerrit's own existing documentation in some helpful way, and avoid trying to replace it.

@suzmue suzmue modified the milestones: Unreleased, website/unplanned May 25, 2023
@mknyszek mknyszek added FeatureRequest NeedsFix The path to resolution is known, but the work has not been done. labels May 30, 2023
@mknyszek
Copy link
Contributor

As an easy first step, we could probably just add those links to the page.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation FeatureRequest NeedsFix The path to resolution is known, but the work has not been done. website
Projects
None yet
Development

No branches or pull requests

5 participants