Re: [discuss] So what does Gerrit actually get us, anyway?
Davis, Matthew <Matthew.Davis.2@...>
I don't know what the LF integration for GitHub CCLAs is like. However I recently contributed to http://github.com/hashicorp/terraform . That was very seamless. I didn't have to download git-review or learn how to use it or figure out some quirky command and url to upload to based on ambiguous documentation. I just forked, then did `git push origin newBranch`, then used the GUI to make a pull request. Then a bot commented in that PR thread saying I haven't signed the CLA. So I clicked on the link in that comment, read the document, ticked a box, and then the bot automatically changed its comment and a human eventually approved the PR. (Yes, they even have two docs, CCLA vs ICLA) It was that simple.
I think that the design of the new CCLA process means that it will never be as seamless as that Terraform one. There are so many more steps and roles. There are 4 domains to traverse, for code, documentation, signing, and a whole second level of account management. Whereas Terraform was "click here, read this, tick this, done".
The error message when you submit a commit without a signed CCLA is ambiguous. Whereas with Terraform a bot just commented on the thread with a clear explanation and simple link.
Everyone says our new CCLA process is automatic and integrated with Gerrit, but you still have to manually navigate to a non-gerrit domain to set up the CLA manager roles. And you have to know that you need to do that. (From memory the gerrit CLA page doesn’t tell you sufficient information.)
There's the person who signs the doc, and the person who represents the company to LF, who nominates which person signs. But why bother having that second role, if we still have to sign duplicates of the same document for each LF project anyway? It seems like we suffer the cost of centralisation, without taking advantage of any of the benefits of centralisation.
The CCLA documentation is imperfect. I believe this is because it is effectively closed source. The very people who need to use that documentation do not have write access to those Confluence pages. So the people who know what improvements must be made do not have any way to make improvements.
Many other open source projects have a “fork me on Github” button on each doc page. With one click you get taken to the actual file with that content, all in one git repo. You can even edit and submit it solely in a browser for something small like a single-line change to docs.
There are many issues in the docs and website which trip up newcomers but won’t be obvious to experienced community members.
It would be great if we had an equivalent approach for the Tungsten website, to ensure those small issues do get fixed. Once the website gets eventually merged into one repo and one domain, can Gerrit provide such simplicity and ease of page-to-code navigation?
From: dev@... [mailto:dev@...] On Behalf Of Will Stevens
Sent: Tuesday, 11 June 2019 11:07 PM
To: TF Dev <dev@...>
Subject: Re: [TF Dev] [discuss] So what does Gerrit actually get us, anyway?
Valentine, I think your comments are quite accurate.
I know the CLA process has been a major blocker for contribution, and that is not a Gerrit thing per-say, but more of a process issue. I think Vicky and I finally got the CCLA that CloudOps signed a YEAR ago working its way through the system. So, I would agree that this is not a knock against Gerrit.
That said, I think your comment that "In a nutshell, Gerrit is (a bit clunky) code review tool which also does
code hosting, Github is code hosting tool which also does review." is very accurate. The one thing that Gerrit does do very well is gating commits into the main line code. The rules that can be defined around review and validation of PRs is absolutely an area were Gerrit offers a good deal of flexibility. So in Gerrit the reviews and PRs are the first class objects, while in Github, the code is the first class object.
So I guess the question comes back to, is the +2 feature that Gerrit offers a critical feature? Are the strengths of Gerrit really what the community needs?
One of the reasons that the grand majority of open source projects run on Github is because it is easy. It is easy for users to learn the code. It is easy for users to fix documentation issues. It is easy for users to get familiar with the code to then consider becoming an actual code contributor.
If I am a user of TF and I want to dig into some code, I have to do the following:
- Find review.opencontrail.org (through some documentation probably, searching in google wont find it).
- There is no mention of repositories there, you have to figure out that the code is under "Projects".
- But clicking Projects doesn't do anything, oh wait, it made a "List" menu option appear.
- Click the "List" menu option.
- Click on one of the repos. Ok, I can clone it, but where is the code? Where is a README to give me context of what I am looking at.
- Ok, there is no way to get to the code from this screen, lets start over and see if I can find the code.
- Click, click, click, ... oh, what is the 'gitweb' thing on the right, click.
- Ok, great now I see some stuff relevant to this project, but where is the code?
- After much trial and error they are likely to FINALLY find the 'tree' link which actually points them to the code.
- Ok, lets read the README file to make sure I am in the right place. Oh wait, there is not MD renderer, so I have to know how to read Markdown.
- Ok, lets check the code. OMG, my eyes, there isn't even syntax highlighting. Who can read this?
- Why am I here again? Maybe I will just tell my boss that I looked at TF and its not right for us.
VS on Github:
- Google for a project. Oh look, the code.
- A README introduces me to the project, this looks right.
- Now I can browse the code and figure out what is going on.
- Let me link the line of code that is the problem to my coworker so they can have a look.
What is important for the users and the community? I think the visibility and usability of the tooling we are expecting our users and contributors to use is extremely important.
Have you ever seen a Gerrit repo show up in a google search? Nope, because even google gave up looking for the code in that mess...
My two cents as an open source contributor of many projects...
On Tue, Jun 11, 2019 at 3:08 AM Valentine Sinitsyn <valentine.sinitsyn@...> wrote: