Re: [discuss] So what does Gerrit actually get us, anyway?
VM (Vicky) Brasseur
I'd rather we didn't conflate the CCLA/ICLA matter with the question of Gerrit. There are now many Jira tickets dedicated to sorting out the CCLA/ICLA processes (both manual and automatic) and a lot of progress is happening there. I encourage folks to head on over to Jira and follow along with that.
As for Gerrit, I asked because Will and I were working on Docs stuff on Monday, which included finalizing the move of the tf/docs repo to Gerrit, and it turned out neither of us had any insight into why we were moving the repos to Gerrit in the first place, or into whether any other options had even been considered.
If there are technical reasons why Gerrit is required, it would be good both to know and to document those. However thus far in the thread I haven't seen much beyond "we've always done it this way." I've always said that this is one of the most dangerous phrases in the English language and I stand by that.
Full disclosure: I do not like Gerrit and never have. Its usability and user experience are both rubbish. It has a very steep learning curve. It's an impediment to contributions. "It's fine once you get used to it" is no defense against these facts, since most new contributors would rather walk away rather than give it a chance. I saw it happen in OpenStack and I suspect the same will happen (or already is happening) for TF.
I have heard many times, both from the community and from within Juniper, how vital it is to TF to attract and retain new users and contributors. As someone who's been doing the FOSS thing for about 30 years, I can confirm that without attracting a community of users and contributors the project will have a difficult time thriving.
In order to get people to become new contributors, if it truly is a priority for us, WE NEED TO MEET THEM WHERE THEY ARE. Where they are, as we all know, is GitHub. They already know the interface and process, plus they expect us to be there. We are much more likely to grow the user and contributor base if we make it easier for them by using a service and process that they're already familiar with. It drops the barrier to entry to a low enough point that we're more likely to get people popping by to fix small bugs then maybe sticking around to join the community (I have an entire well-researched talk about this, if anyone is interested in seeing the video).
Which gets me back to my original question: Why Gerrit? Is there any reason GitHub wouldn't work? If there are no reasons why it wouldn't work, then I propose we outline a plan for using it instead of Gerrit. I'm aware that we've already done some work getting Gerrit set up, but we shouldn't get blocked by the Sunk Cost Fallacy. Actually *discussing* this now rather than just *defaulting* without discussion could be exceedingly good for the community that we're trying to build.
<dev@...> on behalf of "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: