Proposal: Just Use Github
natefinch opened this issue · comments
Before I begin, let me say that I believe that Google and the go team (whatever we may mean by that term) really want Go to be a true open source, community project. My comments herein are intended to shine light on how the current state of Go's development process belies this fact.
There are two common complaints when it comes to the development of Go itself:
- It's too hard to contribute (this was a whole section of Steve Francia's talk at Golang UK)
- Go feels like it's a Google-owned-and-controlled project that is not truly "open source"
Both of these are exasperated by the fact that the technical workflow that the Go project uses is significantly different than what has become standard" for much of the open source community. The standard being - use Github. Use GitHub as the primary code storage, use GitHub for issues, use GitHub for PRs, use GitHub for reviews. The reasons for this are twofold - one, they are integrated and closely localized. Two, they're what everyone is already using, so there's zero cognitive overhead. I think most of us can create a PR in our sleep.
#18517 talks about accepting PRs... .except that it's not really accepting PRs. It's using PRs as a way to feed code into gerrit. This is going to be a terrible user experience, because it will be disconnected from the normal github workflow. Whatever features Gerrit has over GitHub obviously cannot be translated correctly to github, so the bridge necessarily must be lossy. People will expect to be able to receive comments in a different tab of the same page of their PR... but they will instead have to go to a completely different, disconnected UI on a different domain.
Not only is this a bad user experience, it is yet another signal to potential contributors that they aren't really that welcome. After all, tens of millions of developers use GitHub every day. Projects bigger than Go use GitHub a their main development process in all ways.
Things like The Go project contributing flow is currently configured to work only with Google Accounts. and Our canonical Git repository is located at https://go.googlesource.com/go send not-so-subtle signals that this is a Google project, not really a community project.
The first two lines of the contributing guide are The Go project welcomes all contributors. The process of contributing to the Go project may be different than many projects you are used to.
If the first is true, the second should not be true.
I ran through the contributing workshop at Gophercon 2017. I even had gone through half of it before. I still needed help from one of the guides. It was still arduous. I speak as someone who has written Go professionally 40 hours a week for over 4 years - the contribution workflow deters me from contributing to the Go project. Even after signing up. The fact that it's so different from my everyday workflow just makes the hill to climb too steep.
Other large open source projects seem to do just fine. Look at Kubernetes. It's only 3 years old. And it already has almost 50% more contributors than the language it's written in. It uses GitHub for code reviews, issues, PRs, etc.
In my personal experience, the Juju team at Canonical was approximately 25 full time developers when we switched from using ReviewBoard (which has many of the same features as Gerrit) to GitHub reviews. It was much nicer to have the reviews available in the same page as the PR itself. It was nice that the workflow was the same we used for our side projects. It was nice that contributors didn't have to learn new tools and create new logins on external sites. It was nice not to have to maintain those external systems.
When Google keeps the canonical git repo in googlesource, and uses a google-run gerrit instance for code reviews, it does not make the project feel like it's open source. It makes it feel like it's a google project that they let the rest of us look at from afar, and participate in if we're willing to hike up the mountain.
Let's show the OSS world that Go really is a community-run project. Let's make GitHub the first class citizen that it ought to be in the development workflow for Go. Let's drop the barrier of entry that currently exists even for experienced developers, so that contributing to Go only requires a few clicks through an automated CLA signing process and then normal PRs, reviews, normal git tooling.
too hard to contribute, can't agree anymore!
I've heard on the Gotime podcast and Q&As with the Go Team that Gerrit provides a better experience when it comes to reviewing pull requests.
My question is, what makes a strong argument for Gerrit that Github cannot provide?
I ran through the contributing workshop at Gophercon 2017. I even had gone through half of it before. I still needed help from one of the guides. It was still arduous. I speak as someone who has written Go professionally 40 hours a week for over 4 years - the contribution workflow deters me from contributing to the Go project. Even after signing up. The fact that it's so different from my everyday workflow just makes the hill to climb too steep.
I've been writing Go for over five years and contributing in various forms, and I have to say I agree. go-contrib-init makes things better, but the barrier to contributing to Go is a lot higher and with a different workflow from almost any other project that uses Go.
Gerrit does provide a better experience for code review than Github does, though that difference has shrunk over time. At the time Go migrated to Github from Google Code, Github didn't even support split views for diffs! Gerrit still supports a number of things that Github doesn't, but the difference has narrowed significantly. And in my opinion, the opportunity to have more contributors and contributions is enough of a benefit to outweigh the product advantages that Gerrit has when viewed in isolation.
I couldn't agree with this enough, one of the things I hear most in the wild is how hard it is for people to contribute to Go. As successful as the contributor workshop at Gophercon was, it is an embarrassment to the language that we had to do it at all. Why did we need an entire seminar to teach hundreds of developers who already contribute to many other open source projects how to contribute to Go? I think the avenue in which we interact with the Go source code is hands down the culprit.
If we need concrete data in the guise of experience reports I am happy to provide it.. But honestly I think this issue is probably going to turn out as enough.
I agree that GitHub is closing the feature gap, but Gerrit reviews are still a different experience, which I personally find superior. So I think this should configure as a discussion on the tradeoff between review experience and new contributor experience.
But there seem to be two other sentiments in the proposal which I feel like are unrelated and personally disagree with.
First, that GitHub is "the one true way". I don't take seriously the complaints at the other end of the spectrum like "git was supposed to be decentralized!!!11!" either, but "it's not GitHub" should not be an argument against a workflow per-se, beyond the onboarding inertia, nor does all code need to be hosted on GitHub.
Second, the Google ownership part. Technical infrastructure is IMHO both much less important than people (which the Go team seems to be aware of and working on) and wider than Gerrit. TryBots run on Google infra, releases run on Google infra, the website runs on Google infra. And personally I'm glad the community doesn't have to piece it together.
Back when I hosted my code on BitBucket and mercurial I noticed that people would download my hg repo, make their changes, and then upload it to GitHub, and never sent me a patch.
Obviously not great. So, I moved everything to GitHub. Not because I especially like GitHub, but because git and GitHub have become the de-facto idiomatic tools for open source software development.
I still consider mercurial/BitBucket to be superior – but GitHub is certainly an adequate solution, and using idiomatic solutions is an advantage in and of itself. In that sense it's similar to the Go proverb of "gofmt GitHub is no one's favourite, yet gofmt GitHub is everyone's favourite".
I would say that the question "is Gerrit better than GitHub reviews?" is the wrong one. The question should be "is Gerrit so much better that we want to skip out potential contributions?"
I don't have to work with these tools daily, so I don't presume to be able to answer that question. We work with GitHub reviews daily at my day job, and while it's certainly not the best system I've worked with, I do find it an adequate system.
We disagreed a bit on Twitter, but I do share your sentiments.
Switching to GitHub means GH is the sole source of truth for Go. This means if anything happens to GitHub—outages, data loss, whatever—or if GH does anything to its product—API limits, changes that break Go's workflow, etc—Go is out of luck. The Go project can avoid those problems if it uses an OSS tool, like Gerrit or GitLab.
Like I mentioned on Twitter, I wonder if the onboarding process could be made smoother if the docs received some TLC. (That doesn't speak to the part of your issue about Google's ownership, however.)
Agreed. I'd be much more inclined to contribute if not for the contribution process.
One of my previous contributions was closed due to inactivity. I submitted it ages and ages ago, and had no idea it had been reviewed or commented on. After a long time, it was closed cause I didn't respond.
I happily would have responded and finished out the change had I received notification that it had been reviewed. No idea why I didn't get an email or some kind of notification, but I simply threw up my hands at that point. Not worth the rigamarole.
I don't really think it's worth worry about "what happens if GitHub does X". If that happens, Go can move somewhere else (presuming there's off-GitHub backups, which I didn't even bother to mention because of course there would be). But in reality, github's not going anywhere, and they're not going to do anything to screw up the hen that lays the golden egg.
You might as well say "what if Google goes under?" I mean... they actually have closed down one of their source control hosting services :)
The language spec is easier to read than the contribution guidelines
@natefinch I'm not sure if there are tools to backup github issues, but if there aren't, that's yet another reason to switch wholeheartedly to github: the same things which make github better for the Go team will make it better for everybody.
bravo! I wanted to help add support for negative numbers in text/scanner and see the collaboration guide does not invite me to do it
registering a google account on a mandatory way, or accepting a contract to cede code to a project that is already OSS, sucks.
As a person who reviews patches, it seems to me that Gerrit continues to provide a much better mechanism for patch review than Github. Even with our current contribution process, there are many many more contributors than there are reviewers.
@nasciiboy Whether we use Gerrit or Github, all contributors will be required to sign the CLA to give us rights to distribute the contributed code. That is non-negotiable.
Yeah, I wasn't assuming the CLA would go away, but hopefully it could be a trivial click through process that could use your GitHub id so you don't have to sign up for anything.
I speak as someone who has written Go professionally 40 hours a week for over 4 years - the contribution workflow deters me from contributing to the Go project. Even after signing up. The fact that it's so different from my everyday workflow just makes the hill to climb too steep.
I agree completely with this, but at the same time it doesn't feel right to expect the top contributors to tailor the workflow for the rest of the potential contributors. It seems important, at least to me from a quality standpoint, that those who review the most code have the easiest time doing it, as they are the gatekeepers of quality.
I'm not saying it should be harder to contribute to keep contributions away, just that the write-access (or pull access) should not be optimized at the expense of read access (code review, ease of use, etc).
I myself had kept away from contributing due to this very reason for a very long time. Recently though, I just sat down and forced myself to go through the contributor doc. Hardly took me 15 mins, and then I was up and running ! And this was even before go-contrib-init came out !
Yes, the gerrit workflow is something new, and like anything new, people (including me !) are reluctant to put themselves through the time and energy of learning that. But IMHO, its too small of a learning curve to complain about.
Agree with @ianlancetaylor that Gerrit does provide a better way to review patches.
And like @FiloSottile said, the TryBots do run on Google hardware. If we are talking about moving away from Google completely, I doubt one can run tests on all platforms and with the speed the current TryBots do.
Not relying exclusively on Github doesn't make a project any less community-driven. It simply does not compute.
You make it sound as if Go was some kind of weird outlier when in fact it is very common for bigger open source projects to use Github mostly as a fancy mirror while the primary repo and code review live somewere else.
Just drop the CLA entirely. This is corporate nonsense used to make the lawyers feel happy and benefits none of the hackers. Everyone knows that inbound=outbound. #NoCLA
I'd love to see GitHub doing some improvements to the comment handling. There is currently no way of drafting replies when replying to a code review, or there is no mechanism that counts the addressed and non-addressed issues. It is a major step down if you are reviewing long and complicated patches, the way the Go project often does.
I don't care about the CLA or where the main repo is. It's just too hard to contribute.
Gerrit might be nice if you use it all day or even once a month, but, if you look at it maybe once a year, it's a mess.
The rest of it isn't that bad, though the contribution guidelines are hard to skim. It's not bad if you actually read it but if you just open it up with the goal of "to do X I need to do Y", well, buckle in. By the time I figure out what to do I've lost any steam I had to actually do it. Eventually after many months, I'll try again but by then I've forgotten what to do and the cycle repeats.
@cespare You can only create an initial draft. Responses to the initial comments cannot be drafted. Am I mistaken? I use GitHub PRs for everything else and it is such a chaotic experience even for tiny projects.
This proposal is based on things that I disagree with almost entirely. Moreover, some of them are IMO false.
Several people agreed to the claim that's it's hard to contribute. Yeah, you may have to learn a couple of new things. Maybe you make some mistakes in the first case. Trial and error, less than 30 minutes, I guess, and basically only once and forever. We are programmers, we are used to learn new things every single day of our profesional life - or we are soon out of business. (Good luck to the exceptions.)
TL;DR: I see very little technical ground justifiyng the proposal. Only same strange mix of activism and/or policy making. I am very much against.
@rakyll Yes, I think you're mistaken. You can respond to a PR review by doing your own review which works the same way (except that you can't approve/disapprove your own PR). You do this by responding to a comment with "Start a review" rather than "Add single comment". I think this is only available on the "Files changed" tab, not the "Conversation" tab (not sure why). See pic:
I don't have strong opinion.
Go developer team have to manage issues or pull-requests which is not really issue. For example, complaints, dissatisfaction, biased benchmark results. If PR will be opened, meaning-less PR possibly be sent. I have seen a pull-request where all sources are deleted in other project. Ofcourse, we doesn't want it.
Also since we can do anything on GitHub with only few clicks, there are possibly mistakes that will occur. This can be recovered but it should be carefully. For example, the counting of LGTMs like Gerrit (maybe rakyll mentioned).
I think that using Gerrit still have meaning since gerrit have better way for reviewing. In other thing, I am not a Google believer, but I think, Not to use GitHub may be possible way to raise the contributor's threshold. (Please do not treat this as wrong) This can ignore users who doesn't have development intention that mentioned above.
IMO, I don't think it's not hard to contribute to Go as you think.
This proposal is rather large in scope and the discussion could be more productive if broken out into more specific bits to avoid derailment (talking about the CLA, for example). The primary (and most contentious) issue seems to be that of moving away from Gerrit to use GitHub PRs for code review. I suggest you make this proposal more specific to that issue, because it's the one that a lot of your other sub-proposals hinge on.
I 100% agree that it is more difficult to propose a change to Go than to say, Kubernetes. This experience is something we're trying to improve on and the contributor workshop at GopherCon was a great demonstration of the roadblocks some of our community members run into by using Gerrit and our current tooling. We should do better.
While switching to GitHub would potentially make a contributor's workflow more straightforward, the same cannot be said indefinitely for the reviewers. Switching to GitHub PRs would regress the review experience for many, so the success of this proposal hinges on identifying those regressions and either convincing the maintainers that the corresponding benefits outweigh the sacrifices, and/or coming up with a plan to build tooling to fill in the gaps left by switching.
Restricting developers because of a cumbersome process is not good imho. I think anything that makes it easier to contribute is good and this proposal is definitely a step in the right direction.
I wonder if the arguments "You will get used to Gerrit" can't be just as easily applied to Github and it's different review process. Perhaps using Gerrit is more about habit than it being actually better?
I think anything that makes it easier to contribute is good and this proposal is definitely a step in the right direction.
That statement is easily proven false. Requiring no code review at all would make contributions easier, yet wouldn't be at all a good change.
Perhaps using Gerrit is more about habit than it being actually better?
The various reasons for why Gerrit is a better tool have been presented before, here and in previous threads discussing why Go uses Gerrit instead of GitHub. Furthermore, it cannot be about habit – when the Go issue tracker and code mirror moved to GitHub, Go was using Rietveld, not Gerrit. Using Gerrit instead of GitHub was an active decision, based on arguments that hold true to this day, arguments that this proposal doesn't address. In fact, this proposal is only concerned with making contributions easier for first-time or infrequent contributors, and doesn't take the point of view of reviewers and frequent contributors into consideration at all.
I've worked in some places where we've migrated from GH Pull Requests to Gerrit for the reason that GH Pull Requests (until very very recently) were not ideal for a formal review process. Even with the recent changes, the current PR system in GH does not manage revisions of a changeset well. For example, Gerrit includes the commit message as part of a review which is arguably the most important part of keeping a clean and detailed history.
Larger projects then this are in Gerrit (hello Android) and Gerrit is a well maintained and up to date piece of software. If you know Git well, Gerrit is great. Github hides a lot of things from you. The documentation for Gerrit is likely the issue - I've written a lot of 'Day in the life of' Confluence pages explaining Gerrit to people.
The argument that the process of pushing to a different endpoint is cumbersome? Really? That does seem far-fetched. The setup process for a new contributor has massively improved over time as well. It used to be a lot more difficult.
http://nurmi-labs.blogspot.com/2017/01/patching-ess.html
I recall earlier this year regarding collaborating on a minor patch of ESS, when one of those involved mentioned a Github pull request, the reply from the coder to whom the subject was addressed was that he has an epidermic reaction to such large & centralized entities.
I would prefer if Go would continue to utilise the Gerrit project.
I like the corporate and individual CLAs.
https://golang.org/doc/contribute.html#auth
"Gerrit uses Google Accounts for authentication."
Though I would prefer there were implemented an alternate to the use of Google Accounts for authentication; and, indeed perhaps that information could be hosted on machines outside of the U.S.A., and, in that regard I would suggest the location of Bratislava.
That doesn't make it false @dominikh just falsifiable.
If Gerrit is truly better then why isn't it more widespread? It can also be argued that Gerrit is nost as good as the kernels way of using email and patches. Then you can use whatever tool you want to review and thats that so the fact that someone likes ("thinks X is better") something isn't really an indicator other than that that person likes it.
Please don't do that. Githubs PRs (Bitbucket/Stash being no different) mimick plain git pull request and are simply inferior to Gerrit for what it should be used: Review and discuss a single change. It is just too easy to drop a PR containing all the ugly gore of its creation (the sausage making). The next step after switching to Github PRs will be adoption of gitflow, just because so many people are used to it and it would make their lives so much easier.
I agree that working with Gerrit and the codereview extension would benefit from a bit more documentation which could be more tasks focused. But the contribution process is not really complicated. Its git change and git mail and git sync. (I agree that change and sync and how they interplay with branches should be better documented).
If this is a open source political statement to host Go on Github then please do not mix it with the use of inferior tooling.
@natefinch I hope so! But, that's just the thing—the Go community has zero control over what GH does. Companies host their own repositories for this exact same reason. I think your proposal would do well to think about other OSS code review projects are both easier than Gerrit and that could be used instead of putting all Go's eggs in some corporate basket.
It's not that I have anything against GH or corporations, really, it's just that saying "We must couple our infrastructure and tooling" without considering decoupling them seems a bit... shortsighted to me.
Well @vdobler it has always seemed like a tooling issue and then it becomes a matter of taste unless it is actually too slow or simply doesn't work but that is not case here.
I like Github and a lot of stellar developers and projects use nothing but Github so it is not about skill or competence but simply of taste. Thats my opinion at least.
Coding exercises (for fans of hg and git).
http://wiki.9front.org/bounties
fully functional, read/write hgfs
fully functional, read/write gitfs
@vdobler If you think that gerrit is so great, why are you allowing GitHub PRs for your own projects like https://github.com/vdobler/ht and https://github.com/vdobler/chart ?
We want to use GitHub PRs for exactly the same practical reason that you accept GitHub PRs for your projects: every potential contributor already knows how to use GitHub for making contributions to GitHub projects.
I'm pretty sure if you were to tell people they have to read a contribution guide and use unfamiliar tooling, you would get zero contributions to your projects.
Go is significant enough to get contributions despite arduous contribution process but it certainly turns away significant number of potential contributors, myself included.
I applaud that Go team recognizes that as an issue but if attempted solution is unscalable in-person tutoring that achieves worse results than bigger, more active projects (Swift, Tensorflow, Visual Studio Code, TypeScript, .NET to name just a few) then maybe it's time to ponder why Apple, Microsoft and even other Google employees are capable to be productive using GitHub UI for reviews AND make contributing easy.
There are thousands of projects on GitHub, quite a few bigger than Go, yet as far as I know Go is the only one that insists on this semi-hosting on GitHub and insisting on using separate tooling for submitting contributions.
Even with the recent changes, the current PR system in GH does not manage revisions of a changeset well.
I'd like to explicitly reiterate this. I review large PRs all the time. They often have multiple updates over a significant period of time as a PR iterates towards acceptance. In github, when rebase workflow is used (almost universal) I cannot see the difference between different updates. That is, if I ask for some changes to be made, I cannot see whether those changes have if fact been made. This is crucial! Without this feature, reviewing takes longer and is more error prone.
Even if the submitter remembers to avoid rebasing before submitting an update, the changes are still lost when the branch is rebased when the PR is accepted. When diagnosing problems, it is incredibly useful when I can go back in time and see the full history of a given commit. Github does not make that possible. This for me is the main reason that I don't believe Go should move to using pure github reviews.
Are the changes that led up to a particular change set really that important @rogpeppe ? I understand it can be valuable in some instances but isn't the resulting change set what matters and even what should be reviewed? The fact that it took a hundred steps or just a few is not that relevant right? Perhaps I am simplifying it a bit but when I look at source history I prefer atomic meaningful changes that are free of tiny nitpicking "fix" commits.
There are already some third-party plugins for code review like reviewable.io. If Gerrit can be integrated nicely like reviewable.io, then not only the Go team can still have the best experience, other projects on Github can benefit from it as well.
Are the changes that led up to a particular change set really that important @rogpeppe ?
Absolutely. I regularly go through the code history and read discussions on changes (sometimes from years ago!) in order to understand why something is the way it is today. On Gerrit, it's fairly easy to follow. GitHub's PR review system makes it really hard for me to follow the discussion that occurs on a PR after the fact. I'm speaking as someone who uses both Gerrit and GitHub's review system.
Point taken @dsnet I get that going through the discussions can be very helpful to understand why something is the way it is. I don't think Gerrits upper hand outweighs the easy of contribution though.
Is there an ongoing effort to get GitHub to add some of these important features, such as PR revision tracking? I would be in favor of this proposal if it was coupled with reducing the pain that changing to GitHub would have on reviewers and maintainers.
If the intent is to switch to GitHub as it is today, I lean against the switch. As others have pointed out, the number of reviewers is relatively small and the quality of reviews would drop, given that the tool is just not as powerful.
+1000
Use usual workflow with github = really open source and a lot more contributers
While I do agree that GitHub has improved a lot and that the PR system has become better (and more closely aligned to that of Gerrit), I think that @dsnet clearly makes a strong point here about GitHub making it difficult to follow history. Until then, Gerrit holds the upper hand.
While I would like to have GitHub used for the sake of simplicity in the process, I think that switching at this point would have the opposite effect. In my opinion using Gerrit does not make the project less community-run. Everybody is welcomed to contribute.
Additionally, as far as I know, Gerrit stores all the review data in a ref on the project (refs/changes/*, refs/review/*, etc). This can be fetched if you ever wish to move the repository without losing history. GitHub on the other hand owns all your PR data and I personally don't know of an easy way to extract it (although there are some backup tools).
Is there an ongoing effort to get GitHub to add some of these important features, such as PR revision tracking?
Whenever I've asked on this topic - GitHub is really cagey about what they do in this area. They run a very opinionated shop (which is good, it made them the success they are!) but the result is feedback seems rarely listened to. In fact recently had a run in with their sales drones who were claiming that our Org. didn't own the rights to our repositories (I kid you not!)
There are already some third-party plugins for code review like reviewable.io. If Gerrit can be integrated nicely like reviewable.io, then not only the Go team can still have the best experience, other projects on Github can benefit from it as well.
Replacing one external tool with another doesn't seem like the right fix for anyone.
As a day zero Go contributor I appreciate efforts that make contributions easier for everybody. But we don't just want any contribution, we want high-quality contributions. "Open-source" is not a quality seal per se. Thorough code reviews are a primary mechanism to raise and maintain high quality, and thus the code review tool is of primary importance. The selection of Gerrit was a deliberate choice. In fact we would much prefer much more sophisticated code review tools (and we use one inside Google). I think any move to a different system (incl. just Github) would have to provide at least as good a code review experience or better.
In fact recently had a run in with their sales drones who were claiming that our Org. didn't own the rights to our repositories (I kid you not!)
That sounds troubling.
As it stands - for me, even being an external observer, reviews for the complex patches like ticker per goroutine and GC patches are a must. Gerrit is just that better at following the "train of thought" in such code review.
FWIW I think that small code reviews would be just fine with pure github. I'm thinking things like typo correction, adding examples, fixing doc comments. It's hard to know where the line should be drawn though.
@kjk I should be honoured that you compare my little toy projects with Go. Thanks!
But the comparison (and thus your argument) is lacking: I accepted 11 PRs for chart in 6 years, the last one 2 years ago. For ht all 4 PRs came from a colleague and we discussed these tiny fixes over a coffee.
PRs on Github are fine if you have to handle 15 in 6 years, let's say one PR every three month. But any workflow and GUI would do so this doesn't prove anything.
You mentioned "thousands of projects on GitHub, quite a few bigger than Go" who are happy with Github PRs. This is fine but no argument that Github PRs are good enough to replace Gerrit (which is better and offers more features).
You argued that "Go is the only one that insists on this semi-hosting on GitHub and insisting on using separate tooling for submitting contributions". I might be wrong but git itself and Linux don't do github PRs for contributions.
@kjk Just as another example, Clojure is hosted on github, however all contributing is done elsewhere.
//edit - IMO it suffers all the same problems, contributing is way too hard so many don't.
Switching to GitHub means GH is the sole source of truth for Go. This means if anything happens to GitHub—outages, data loss, whatever—or if GH does anything to its product—API limits, changes that break Go's workflow, etc—Go is out of luck. The Go project can avoid those problems if it uses an OSS tool, like Gerrit or GitLab.
Agreed. GitLab's own review tools have vastly improved. The per-commit review process of Gerrit (which has been widely said to be lacking on GitHub and as such often evaluated as a major showstopper) is already possible in some way on GitLab, and scheduled for improvement, or very open to such (here, here, here, and if you want it please make your voice heard). GitLab's way of operation is sufficiently close to the one of GitHub to be easily approachable by the community at large, and much more palatable than the one of Gerrit. I have heard strange points being made about the latter as being some sort of "barrier to entry" to contributions, inasmuch as a worthy contribution should be coming from a contributor that is supposed to be able to withstand whatever strangeness the review process imposes on him.
The trump card here in favour of GitHub is that Go code has been migrated to GitHub recently, so it's already there and going through another migration may be painful.
Point of note: GitLab may or may not != gitlab.com.
I've contributed a few times to Go and the Gerrit learning curve exists, no doubt, but after 30 minutes I easily got the hang of it. In simplest terms, it's replacing push with mail (and amending commits instead of making additional, which I prefer anyway). I actually liked the review experience so much with Gerrit in my few Go commits that the company I work for switched to Gerrit for all of our projects. I think the argument for ease of use makes sense for smaller projects where the incentive to contribute is lower and reviews are smaller, but at the scale of Go, it should really be up to the reviewers what is the quickest for them. Does it make sense to inconvenience the few reviewers for the convenience of contributors, especially given the inconvenience is less than an hour the first time?
I think the argument for ease of use makes sense for smaller projects where the incentive to contribute is lower and reviews are smaller, but at the scale of Go, it should really be up to the reviewers what is the quickest for them.
I agree. I would consider adding the point that quality > quantity when it comes to contributions on something so depended on the world over. I remember all the early day releases and breaking changes! So for me, it's about the quality of the reviews. If people reviewing need Gerrit to do that work, then that is what should be used.
I think the argument for ease of use makes sense for smaller projects where the incentive to contribute is lower and reviews are smaller, but at the scale of Go, it should really be up to the reviewers what is the quickest for them.
True enough, yet if the reviewers have to spend an inordinate amount of time training contributors or fixing a mess because of some impedance mismatch then it's a losing proposition.
Not using GitHub is a good litmus test for contributors, keeps the bad ones out of the patch queue!
You would have more reviewers if you used GitHub code reviews.
I truly don't believe the hype that Gerrit produces better code for the project because of its features. I've used ReviewBoard, which has all of the features mentioned in this thread and others, and it did not produce any increase in overall code quality or increase the speed of reviews.
Not using GitHub is a good litmus test for contributors, keeps the bad ones out of the patch queue!
Keep the people eager to get into contributing out?
The people who may have some great, creative, innovative ideas and just need a bit of review and refactor from the community to get them on board with contributing?
There's a reason reviews exist. I don't think anyone would agree with pushing eager contributors away from an open source project.
Eagerness doesn't make for good patches. What kind of person is eager to contribute to a compiler but not eager to learn a new (maybe even superior!) tool? Answer: the kind of person whose patches are probably not worth reviewing.
I read through all the comments in this already very long thread, which I do not want to make longer but I feel it is necessary to point something out.
Most of those commenting are not putting themselves in the other persons shoes. We have on one side contributors, and yes I agree contributing to Go is more difficult than other project. On the other side we have the reviewers, and I also agree Gerrit is a better tool for patch review. I have worked on large projects on GitHub, yes even with the new code review, and Gerrit is a cleaner approach. It is better for code review in my opinion. It uses the features in git better as well. It took me awhile to get used to Gerrit which does prove there is a barrier to entry but I think the people in this thread need to stop dismissing the needs of the reviewers and more work towards how we can make GitHub work for them. Because honestly maintaining any large project on GitHub or off is insanely difficult and arduous.
I have the impression that, besides inertia, the resistance to move from Gerrit to GH has a great deal to do with the degrading workflow experience for the reviewers. This is very valid.
However, if it is so, it contradicts the message that The Go project welcomes all contributors. No it doesn't. It welcomes those who have the time to contribute so frequently they don't need to refer to "the guide" anymore, or those who don't contribute so frequently but also have that time.
I for one have some TLS related examples I want to add but every time I think about doing that I realize I need to carve out time to also read "the guide" first, and keep postponing it. My (first and) last contribution was so long ago I no longer remember the workflow.
So one trade off that seems center stage to this question is: is the Go team willing to give up some usability experience to have more contributors?
Another issue related to this that we could think about: with a lesser reviewer experience + more incoming contributions, in case the code base is moved to GH, would life for the Go team not be made much worse in terms of getting PRs reviewed and accepted? I think one answer to that is to add more reviewers?
However, if it is so, it contradicts the message that The Go project welcomes all contributors. No it doesn't. It welcomes those who have the time to contribute so frequently they don't need to refer to "the guide" anymore, or those who don't contribute so frequently but also have that time.
"The Go project welcomes all contributors, except for those who can't be bothered to learn our review process, coding style, unit tests, won't follow up on review comments..." This is a tautology. Contributors who won't bother to learn how the project is governed are worth their weight in dust.
I prefer open source projects personally even though GitHub is nice Gerrit or GitLab would be better choices.
more work towards how we can make GitHub work for them. Because honestly maintaining any large project on GitHub or off is insanely difficult and arduous
I agree. Perhaps we could consolidate a list of the attributes of Gerrit that reviewers prefer over Github, to see what needs to be bridged and provide a framework for doing so.
From skimming this thread, the two that I noticed mentioned already were:
- Draft comments in reviews (possibly already supported by Github?)
- Keeping a tally of outstanding issues on a pull request
though that's not a complete list.
Hi,
After reading this and having some experience with getting contributors to send patches to Go (via Gophers Slack and real-life) here is what I can see.
First, this issue and its comments:
- there are quite a few people who have not contributed to Go at all asking for Github to be the primary way of doing contributions in order to make things simpler
- there are a few Go contributors who think that Go must strive to make the contribution process easier and Github would accomplish that
- there are a few Go contributors who see the value in Gerrit and the way it works
Now from the non-issue side:
- people have big problems with setting up the environment for working Go correctly
- I've never had to explain Gerrit to anyone that had a working patch for Go. However I did had to explain how to setup the environment so that Go can be developed.
Based on evidence from active maintainers of Go, it seems that the real problem is the fact that there are too few reviewers compared to the number of patches they are receving.
Looking at Gerrit, this does seem to support the statement.
Personally I don't see a problem in using Gerrit. For the few times I had to use it felt very intuitive and easy to use.
So then what's to do with contributors and their numbers?
The problem that this issue wants to address seems a non-problem, just by looking at the numbers from Gerrit.
It's not the lack of code commiters that send patches to Go, it's a problem of having them reviewed, improved and merged.
Contributors don't necessarily have to be code commiters. They can be people that check the PR and review it, have helpful comments, support people working on PRs, help writing documents and so on.
Moreover, the quality of the contributions needs to be in line with the current contributions as well as having the same level of support for them as today (if not better, in both cases).
In my humble opinion, the real problem is that this page: https://golang.org/doc/contribute.html is really not up geared towards making the process easy.
When I've first tried to send my first (and only) contribution to Go, that page just made me question everything. It's not a friendly page by all means, the structure is bad, the examples are poor and half open.
Those are the exact kind of problems that are solved with posts like this: https://medium.com/@vCabbage/go-testing-standard-library-changes-1e9cbed11339
People need to have an easy workflow to contribute and Github is familiar for many, but it's not the only one. Once learned, the current tooling is rather enjoyable and easy to use as well.
And to end this with a question: If people are so eager to contribute to Go but they find the process hard to do and give up so easily, would you really want that person to contribute to begin with? Because that's a signal that the person might not stick around to maintain it so someone else would need to pick it up. What contributions are being missed because of this issue?
P.S.
Am I a bad contributor because I've not fixed the page I'm complaining about or not even opened an issue? Yes, that's true. Unfortunately it's not a top priority for me so I never get around fixing it and my time is very limited.
Contributors who won't bother to learn how the project is governed are worth their weight in dust.
You are conflating learn, which in this case here is an attempt to demean a person's intelligence, with memorize.
To add to @ChimeraCoder's list #21956 (comment):
- commit message review
- most importantly, patch revisions that allow seeing how a patch evolved over time (GitHub allows this in a very very fragile form if the author never rebases, and the submitter uses squash-and-rebase and rewrites the commit message not to be a long list of "
fix comments")
Any reason we are not willing to give #18517 a chance at being a compromise where small contributions can come via PRs, but complex reviews are done on Gerrit?
People need to have an easy workflow to contribute and Github is familiar for many, but it's not the only one. Once learned, the current tooling is rather enjoyable and easy to use as well.
When you speak in terms of "easy", you are demeaning people's intelligence. The issue here is NOT that people can't learn the workflow. The issue is not that it is hard to learn. The issue is that it is not familiar. It is a process that it is different from what most of us use everyday.
When you speak in terms of "easy", you are demeaning people's intelligence. The issue here is NOT that people can't learn the workflow.
I was not referring to their intelligence as I can't quantify that.
The issue is not that it is hard to learn. The issue is that it is not familiar. It is a process that it is different from what most of us use everyday
Thus they shouldn't be scared to try something new / different :)
Thus they shouldn't be scared to try something new / different :)
Says who, you? What is your argument? Mine is that it is a barrier to contribution. It requires context switching.
Thus they shouldn't be scared to try something new / different
I'm in the same situation as @carlisia and others in this thread. I've tried the "new / different" way, I've submitted CLs, but I don't come back regularly. I work on Github all day and, not being a frequent contributor, I have to completely switch gears to a different style of work for Gerrit.
That said, I think this issue would be better served if we focused on the list @ChimeraCoder started and @FiloSottile expanded. Understanding the trade-offs the current frequent reviewers would have to make is crucial.
The point that reviewers should have it easy is a perfectly cogent one, but – paraphrasing a well known adage – it should not make trivial contributions any less trivial to submit. Everyone's time is valuable, and the review process is a communication tool that should empower both the reviewer and the reviewee.
Says who, you? What is your argument? Mine is that it is a barrier to contribution. It requires context switching.
I'm in the same situation as @carlisia and others in this thread. I've tried the "new / different" way, I've submitted CLs, but I don't come back regularly. I work on Github all day and, not being a frequent contributor, I have to completely switch gears to a different style of work for Gerrit.
But this all points to a very different problem: lack or improper documentation.
Why is it a barrier of entry? Because of the UI? Because of the fact that instead of git push you do git sync ? Because people need to signup to Gerrit as well (which would need to anyway to manage their CLA)? Because of the Gerrit UI which can be used in the same way as Github?
Where are all the issues in Slack, Reddit or golang-nuts asking for help with Gerrit because there's a contribution that's sitting in a branch but the author doesn't know how to use Gerrit? Did someone asked and it was not immediately replied with an answer that's helpful?
And let me put it very bluntly: what contributions do you have, sitting right now in branches in your local Go development setup that you cannot push because Gerrit is too complex to use?
So, you'd rather have the Go team rebuild their infrastructure around Github for the next 6+ months or you'd have someone in the community contribute better documentation on how to contribute to Go?
What I'm saying is: all these assumptions start from the wrong end of the problem: fix the docs, fix the tooling then, finally, if all else fails, migrate to github. Not the other way around.
Or, the other way around: migrate to GitHub and try it out for a while.
Or, the other way around: migrate to GitHub and try it out for a while.
Again, So, you'd rather have the Go team rebuild their infrastructure around Github for the next 6+ months or you'd have someone in the community contribute better documentation on how to contribute to Go?
You're missing the point @dlsniper. This isn't about having problems with Gerrit. This is about how different it is, how it requires everything you described: a different UI, a different git subcommand, a different signup process. None of these things are huge issues, but they're a lot of paper cuts that add up and push people away.
I understand that none of these bother you and that's fine but they do bother some of us. Perhaps many, given how many people left reactions on @natefinch's original post.
And, again, I don't want to be dismissive of the many changes that would need to happen for the Go team to do this. It might not be worth to do it in the end but it certainly is worth considering what would change and if we can live with it.
Again, So, you'd rather have the Go team rebuild their infrastructure around Github for the next 6+ months
@dlsniper has a point, time wasted on migrating infra around GitHub is just not worthy. It will take a long time for it to work properly, just to gain an amount of contributors that (sadly) can't fully understand the contribution guide, thing that can be improved by the community.
or you'd have someone in the community contribute better documentation on how to contribute to Go?
Quality > quantity, and some of those changes may be really disruptive for the language itself, though.
Oh, and a note on reviews of large patches. Looking at Gerrrit, ~95% of currently open CLs are under 500 LOC. ~99% are under 1500. (these are visual estimates, I don't have tooling to get concrete numbers). So, the benefit of gerrit for large reviews seems minimal, since there just aren't that many large reviews (which is good, of course).
In addition, I'll say it again - using familiar tooling will get you not only more code contributions, it'll also get you more reviewers.
So, one thing that I feel wasn't emphasized enough: The history-feature of gerrit isn't so much about after-the-fact reading through the history, but about making the review easier (for both sides). It means, that when I do a lengthy review (I don't use gerrit to review, but a proprietary system with similar features), I can a) do a review, b) send out my comments, c) forget about it, d) come back when they are addressed and e) look at the diffs to my previous reviews and whether they satisfactorily addressed my comments. I.e. just like I trust HEAD to contain good code and thus only check diffs, I trust my previous self to have commented on the correct things and only check diffs against that.
I say that, to make the value gerrit provides a little clearer: Instead of having to review the whole change on each iteration, you reduce the review to only the diffs of the iterations (and maybe an additional comprehensive review once the change converged). That is a huge time-saver for large changes.
Or to put it another way: Someone said up-thread
I understand it can be valuable in some instances but isn't the resulting change set what matters and even what should be reviewed?
you wouldn't suggest reviewing the complete resulting codebase for each suggested change - reviewing produced diffs has clear advantages. Exactly the same goes for large, iterated reviews.
I agree that the current process is cumbersome (though, TBQH, it could probably be split up in the "setup" and "review" phases, some smaller things could be pruned and in the end you'd end up with a fairly straight forward, quick process), that gerrit could integrate better with github, and that github should grow better code review tooling. All of these, I believe, are true and I think there isn't really disagreement about them.
But at least for me, personally, what keeps me from contributing (apart from "finding the time") is knowing what to contribute - where my limited abilities can have the most/best/any positive impact on the project. If I have a patch ready, personally I don't care for what hoops I have to jump through to get it submitted.
@natefinch I think more interesting that LOC/patch would be iterations/review. If I produce 10K SLOC of perfect code, there doesn't need to be any iteration and progress-tracking becomes irrelevant. Meanwhile, if I review 100 lines of code and we need to go through 5 iterations, I'll get grumpy having to read the same 100 lines over and over again.
Oh, and a note on reviews of large patches. Looking at Gerrrit, ~95% of currently open CLs are under 500 LOC. ~99% are under 1500. (these are visual estimates, I don't have tooling to get concrete numbers). So, the benefit of gerrit for large reviews seems minimal, since there just aren't that many large reviews (which is good, of course).
Can you please explain how you've looked at Gerrit to see those numbers? As I can't see them using the Search functionality available https://gerrit-review.googlesource.com/Documentation/user-search.html
I'll put some effort to get an analysis done via the API see how many of these are having comments, what's their distribution over time, how often do the developers abandon them and what's the distribution of comments per line of code for those PRs.
But at least for me, personally, what keeps me from contributing (apart from "finding the time") is knowing what to contribute - where my limited abilities can have the most/best/any positive impact on the project. If I have a patch ready, personally I don't care for what hoops I have to jump through to get it submitted.
I'm very much in the same position as @Merovius.
And I think that's the case for most people that would actually contribute back to Go. I'm trying to teach as many people as I can so that they can contribute to it.
And here's another fact. This issue is: let's just use github. How do you plan to migrate the existing CLs to it? All the history?
It's very easy to think: "migrate to GitHub and try it out for a while" when you have to invest no effort into it.
So far, none of my questions have been answered yet I've been called out for insulting people's intelligence or my questions where completely avoided. Can we have a discussion based on evidence not feelings?
@dlsniper I went here: https://go-review.googlesource.com/q/status:open and clicked "next" a lot. ¯\(ツ)/¯
@dlsniper you should be able to get the data using Maintner (golang.org/x/build/maintner/godata) and the ForeachOpenCL command. If that doesn't work or it's too difficult to get up and running please let me know, I'd appreciate feedback that would make it easier to use.
@kevinburke thanks a lot!
FWIW, I have a number of open CL's that should help (slightly) by adding information to the README for each project about how to get started contributing, where to report errors, etc. the ones marked README here: https://go-review.googlesource.com/q/author:kev%2540inburke.com+is:open+README
I also like how it submits commits messages with who reviewed.
+1. Maintner uses this metadata to get information about who reviewed each CL, plus I (and maybe others?) have used it in the past to determine who's the best person to review a patch in a given directory, via e.g. git log /path/to/directory | grep Reviewed-by: | sort | uniq -c.
I have carefully read the entire discussion thread and believe the question is wrong: why do the project move to GitHub? It is already there and thrives. Yes, the main reviews are done through Gerrit Code Review not really to make the contributors' life more difficult but rather to make the review work more manageable and actually make the overall cycle time of contribution shorter.
The argument of "pushing reviews through GitHub is just so much easier" is the wrong one: the cycle time of a contribution is typically 5% the initial push and 95% the reviews. Are we focusing on optimising the 5% of the problem?
In the Gerrit Community, we tacked the issues multiple times and I have even presented a talk at the Gerrit User Summit in 2015 on the issue: we ended up launching the GerritHub.io free hosting service that has over 20K active users and over 300 companies using it on a daily basis.
In a nutshell, the solution is: take both!
To encourage new contributors to jump onboard and give them an easy way to submit their contribution, they can just create a PR on GitHub and they are automatically imported into Gerrit. Because the integration is done natively at Git protocol level, the GitHub PR is just "linked" to the Gerrit review and, as soon as the review is merged, the PR gets closed.
Yes, the reviews will stay on Gerrit and that is perfectly fine because it is the best tool to optimise the 95% of the contribution process, where the GitHub integration of GerritHub.io allows to increase the reach of the potential contributors and then the "fan-in" of the community.
Accounts? No need to create a Google Account because your existing GitHub account is trusted by Gerrit and your identity, including Public Key and Group Ownership is retained in GitHub and used by Gerrit.
I believe that would be the solution to get both "parties" of this discussion to agree on a common ground to achieve the best of reach and ease of contribution whilst keeping the rock-solid and reliable Gerrit review workflow.
Gerrit UX sucks? Well, we know and lots of people are working on improving it on a daily basis. An entire team called PolyGerrit UX team is spending time in getting feedback from the community and translating into improvements on the user experience.
Is GitHub getting better? Yes, but at a speed that isn't good enough to keep the pace of Gerrit evolution or user needs.
What is the main difference between GitHub and Gerrit Community and users?
-
GitHub: widely used by millions of developers worldwide but driven by a company that drives their profits using its popularity. Gives a free service that we love, but it is very slow in implementing what the people wants and needs.
-
Gerrit: used not so widely but still millions of developers worldwide (mostly in large companies) and driven by the same users using it every day. Still a free service and evolving very quickly towards the needs of who's using it on a daily basis, its users.
Yes, the Gerrit UX isn't widely known, but at the end of the day we are all developers and if we are not willing to learn new tools or frameworks, we are professionally dead and we would still be using mainframes and punch cards after all.
Having said that, I do love GitHub and I use it for my company and my projects as well, with reviews on GerritHub.io of course :-)
For those who are saying that Gerrit CLI is complex, let's remind the two flows:
Pushing code to GitHub requires:
- Fork the repo
- Clone the forked repo
- Create a commit
- Push to GitHub
- Click on create pull request
- Confirm and review your pull request message
... or you install the GitHub CLI, which requires you to learn the 'hub' commands.
Pushing code to Gerrit requires:
- Clone the repo (original, not the fork)
- Create a commit
- Push to Gerrit (
git push origin HEAD:refs/for/master)
Yes, I know step 3. requires some "deep knowledge of Git" (the HEAD:refs/for/master) and that's why you may define a super-complex alias called "review" that does that.
Feedback is more than welcome :-)
Luca.
FWIW I think that small code reviews would be just fine with pure github. I'm thinking things like typo correction, adding examples, fixing doc comments. It's hard to know where the line should be drawn though.
@rogpeppe how about, if it's an obvious +2 with no need for comments, changes, etc, accept it as a PR? otherwise, redirect to gerrit.
Yes, I know step 3. requires some "deep knowledge of Git" (the HEAD:refs/for/master) and that's why you may define a super-complex alias called "review" that does that.
Gogland from Jetbrains has a Gerrit plugin which does this for you as well. If that's of any help to anyone?
@leepa the Eclipse Git plugin automatically detects that Gerrit is running on the Server and does it for you "out of the box".
I have never met anyone that is familiar with Git that is not able to do even on a CLI a git push origin HEAD:refs/for/master
+1 @lucamilanesio Also, GitHub is probably going to require more paid add-ons to come close in features. Gerrit is yours to keep, but GitHub may change it's terms or UI.
@lucamilanesio
Or — just like installing the commit-hook (for Change-Id) — let users initialize the local repository with
git config remote.origin.push HEAD:refs/for/master
So that you can just do git push.
As a day zero Go contributor I appreciate efforts that make contributions easier for everybody. But we don't just want any contribution, we want high-quality contributions. "Open-source" is not a quality seal per se. Thorough code reviews are a primary mechanism to raise and maintain high quality, and thus the code review tool is of primary importance. The selection of Gerrit was a deliberate choice. In fact we would much prefer much more sophisticated code review tools (and we use one inside Google). I think any move to a different system (incl. just Github) would have to provide at least as good a code review experience or better.
All that is reasonable but can you explain what makes Go project a special snowflake in this regard?
Go has ~33k commits.
Typescript has ~20k commits, ~5k PRs reviewed via GitHub interface.
Swift has ~60k commits, ~12k PRs
Rust has ~68k commits, ~21k PRs
Are those projects lower quality than Go? Are leaders of those projects ignorant of superior code review tools? Wouldn't they also want to use the best possible tool?
Or maybe they made a deliberate choice that being an "open source project that welcomes contributions from thee community" requires more effort than paying a lip service to the idea.
That it's about embracing the processes that tens of thousands of other GitHub users know and not about making the community learn your quirky workflows, better as they might be.
The community is pretty clear about what we think is good for community.
The Go Team is also clear what they think is good for a handful of people employed by Google that do reviews and control the project.
Those things are at odds.
Both parties think that what's good for them is good for the project.
Microsoft and Apple and Mozilla show us that you can successfully manage a high-quality, high velocity open-source language project using GitHub alone, in a way that engages community better.
Anders Hejlsberg reviews PRs on GitHub. What makes you so special?
Hello,
I believe the step to Github is a good one to take. I started coding just two or so years ago and still have to make my first contribution to an open source project. The reason I haven’t made a contribution yet is that I simply don’t know what I should contribute. But if I am going to make my first contribution, Go is not the project I will pick. I will be far more likely to contribute to, let’s say, Atom (the text editor); just because I can easily do so at Github with techniques I already learned. It feels familiar.
I am absolutely not saying that making a contribution to the Go project is very difficult or impossible - people do it every day. It’s just that if someone is looking for a project to contribute to on a rainy sunday they might pick another project that they can contribute to via Github over Go: beceause it’s easier, no extra learning is necassary.
Or maybe they made a deliberate choice that being an "open source project that welcomes contributions from thee community" requires more effort than paying a lip service to the idea.
Well, not immediately granting anyone's wish (impossible b/c many are contradictory) is not the same as is very unfairly claimed in the quote above.
But everyone is free to fork the Go repository now and start to accept Github PRs. Becuase Go is an open source project, even when not accepting Github PRs into the repository created by Google.
You don't choose that project, it chooses you. Good contributions arise from problems naturally encountered. Searching for an opportunity to make a contribution has merit but is of questionable efficacy. Using software, your search is already over. If it itches that badly, you'll scratch.
To me the proposal implies a scenario: The problem has been encountered, your solution in place, but the transmission of that solution is hindered by the lack of an accessible transmission/feedback facility. 100% in agreement. The system is unfriendly.
Does that mean it should be changed? I don't think so. It's optimized for the contributors that contribute most, and is running at the expected efficiency. Look at the project's top contributors and the no. commits, insertions, deletions. An inhuman amount of work goes into this project, and decisions to change things should be weighted based on who is doing that work and affected by the changes.