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.

 

--V

 

From: <dev@...> on behalf of "Davis, Matthew" <Matthew.Davis.2@...>
Reply-To: "dev@..." <dev@...>
Date: Tuesday, June 11, 2019 at 10:01 PM
To: "dev@..." <dev@...>
Cc: "discuss@..." <discuss@...>
Subject: Re: [TF Dev] [discuss] So what does Gerrit actually get us, anyway?

 

Hi again,

 

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?

 

Regards,

Matt

 

From: dev@... [mailto:dev@...] On Behalf Of Will Stevens
Sent: Tuesday, 11 June 2019 11:07 PM
To: TF Dev <dev@...>
Cc: discuss@...
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.

- etc...

 

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

 

Cheers,

 

Will Stevens

Chief Technology Officer

c 514.826.0190

 

Image removed by sender.

 

 

On Tue, Jun 11, 2019 at 3:08 AM Valentine Sinitsyn <valentine.sinitsyn@...> wrote:

Hi all,

That's not how it should be obviously. However your story suggests that
the real blocker was CCLA (and I know where you come from), not Gerrit.
Are there any indications that ICLA/CCLA process on Github would be more
straightforward? Is it related to some bug or obscurity within Gerrit
itself, not our processes (which we are trying to fix now)?

I'm not a big fan of Gerrit personally, but it does have some nice
features such as +2 reviewers which are not readily available in Github.
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.

Valentin

On 11.06.2019 4:53, Davis, Matthew wrote:
> Hi all,
>
> For those who didn’t see my previous emails, I’d like to tell my story.
> (I think it’s part of the motivation for Vicky’s question.)
>
> I have about 16 patches I have been trying to submit since February.
>
> I have already submitted some patches to the docs on GitHub, and they
> have already been merged.
>
> That was simple and straightforward, like it /should/ be.
>
> That was just like submitting to any other non-LF project.
>
> But the rest of the code is on Gerrit, which is not straightforward.
>
> Trying to understand Gerrit is time consuming, because it’s a steep
> learning curve.
>
> That can be ok if there are useful features of Gerrit which outweigh
> that high barrier to entry.
>
> So, what are those advantages?
>
> Worst of all is the CCA issue, which is tied into Gerrit. After 4 months
> of trying, I still haven’t been approved in the system.
>
> The old approval system is not working any more. The new gerrit doesn’t
> yet have any code. Everyone talks about how things are about to change,
> but it’s been like this for at least 4 months.
>
> So I am unable to submit patches or raise issue tickets for the main
> body of code.
>
> I am about to move on from my current role to a new one, and my team at
> work is being disbanded.
>
> So after 4 months of trying to get patches submitted, I will have to
> abandon my patches.
>
> Over the last 4 months I’ve had to deploy Tungsten using a custom
> Ansible playbook which applies custom patches that I cannot contribute
> upstream.
>
> If Tungsten was on Github, those patches would have been submitted and
> merged months ago.
>
> But because the code is on Gerrit, (and because of the overbearing CCA
> process) the community will not get those patches, ever.
>
>
> That is the impact of using Gerrit.
>
> In a prior discussion someone mentioned self-hosting as a benefit of Gerrit.
>
> GitHub and GitLab both have self-hosted options if that is a concern.
>
> Other project such as Ansible (on GitHub) have an automatic CCA. (“By
> submitting this PR you agree to … “) So the project still gets the same
> legal protections, but without the bureaucratic hurdles.
>
> I think that is the motivation for the question.
>
> Regards,
>
> Matt
>
> *From:*dev@... [mailto:dev@...] *On Behalf
> Of *Sukhdev Kapur via Lists.Tungsten.Io
> *Sent:* Tuesday, 11 June 2019 9:34 AM
> *To:* dev@...; discuss@...;
> dev@...
> *Subject:* Re: [TF Dev] [discuss] So what does Gerrit actually get us,
> anyway?
>
> This is a very open ended question. What is the motivation of asking
> this question?
>
> Sukhdev
>
> Get Outlook for iOS <https://aka.ms/o0ukef>
>
> ------------------------------------------------------------------------
>
> *From:*dev@... <mailto:dev@...> on behalf of
> VM (Vicky) Brasseur via Lists.Tungsten.Io
> <vmb=juniper.net@...
> <mailto:vmb=juniper.net@...>>
> *Sent:* Monday, June 10, 2019 9:37 AM
> *To:* discuss@... <mailto:discuss@...>;
> dev@... <mailto:dev@...>
> *Subject:* Re: [TF Dev] [discuss] So what does Gerrit actually get us,
> anyway?
>
> Adding dev@, since the devs have skin in this game.
>
> *From: *<discuss@... <mailto:discuss@...>>
> on behalf of "VM (Vicky) Brasseur via Lists.Tungsten.Io"
> <vmb=juniper.net@...
> <mailto:vmb=juniper.net@...>>
> *Reply-To: *"discuss@...
> <mailto:discuss@...>" <discuss@...
> <mailto:discuss@...>>
> *Date: *Monday, June 10, 2019 at 12:32 PM
> *To: *"discuss@... <mailto:discuss@...>"
> <discuss@... <mailto:discuss@...>>
> *Subject: *[discuss] So what does Gerrit actually get us, anyway?
>
> Will and I are sitting here in the lovely CloudOps offices in beautiful
> Montreal, having a little 2-person TF hackathon, and we got to talking…
>
> Real Soon Now™,  we'll be moving the repos from Juniper to Gerrit and
> then mirroring them from Gerrit to GitHub.
>
> But what exactly does Gerrit do for us, anyway?
>
> Wouldn't just going directly from Juniper to GitHub and not do Gerrit at
> all entice more people to contribute and dramatically improve the
> contributor experience?
>
> Neither of us have yet seen an explanation for why Gerrit **needs** to
> be involved at all.
>
> Could someone please explain why it's needed and, if it turns out it's
> not really needed, could we please just not subject our community to the
> misery of having to use Gerrit?
>
> --V
>
>

--
С уважением,
Синицын Валентин



Join dev@lists.tungsten.io to automatically receive all group messages.