Maiao: Gerrit-style code review workflow for GitHub, GitLab, Gitea, others
github.com
github.com
Edit: Just to be clear, this is not a blemish on this project. More a lament and a wish someone would create such a thing for those of us forced to leave Gerrit behind for... GitHub. =/
tl;dr: Adevinta got bought by a Private Equity consortium [1]. Since then, the fund did many changes, and layoffs. All of the original creators/maintainers don't work there anymore.
Runetes is just an umbrella org for some OSS we created there.
1 - https://adevinta.com/press-releases/permira-and-blackstone-a...
sounds like crazy town.
I just dont understand why someone would operate like this.
Lets assume you're squash merging your feature branchs to your local main, then you're raising the them as prs.
why would you do this?
Small commits can often be tested faster, since irrelevant tests don't need to run.
Small commits are less risky. The smaller the delta of change, the lower the probability that something breaks.
Small commits get merged sooner; big commits take time to build up. Merging early front-loads your integration risk; merging later puts integration risk just before delivery.
Breaking a big feature into small commits means using feature flags to control whether a feature is enabled or not (since control paths will generally be incomplete). This means you separate the delivery of the code from the delivery of the feature, and has the added benefit that you can turn off a feature that has a problematic rollout without needing to redeploy code.
I used to work at companies where no one squashed their commits and the entire git logs were filled with 80% non-sense like "temp" or "bad" or "working" with the other 20% being coherent changes. What's the point of doing this I ask?
I quite like that I can tell my colleagues they can commit whenever they feel like it (and should probably commit more often than they feel like) because it becomes one clean commit in the end anyways.
- you apply the commits as-is on the target branch and end up with a ton of pointless "fix this" and "fix that" commits that were created during the review process,
- you squash everything and lose what might otherwise have been meaningful, useful commit boundaries for the purpose of bisecting, reverting or just investigating the history of changes or
- you rework your commits and force push changes to the branch you want to pull and create confusion as to what changed because that's not usually how review is conducted with GitHub.
I think the pull request is a bad abstraction. Not terrible, and certainly easy to grasp, but bad enough that everything you do with it is a compromise. At the very best, if you apply with the squash+rebase strategy and limit the scope of your PRs to what makes perfect sense as just one commit in the target branch, it's just a convoluted way of working with individual commits.
This gives you a very clean log on main (it only shows commits directly on this branch). There is no need to squash, rebase, or anything else. And if you want to dig down into individual commits that happened on a branch, you can!
This can be a bit replicated by forcing a merge type of merge and setting an alias of log to "log --first-parent", but since that isn't the default, that isn't what you see when you look at the commit logs on platforms like github.
I never understood why git decided to show a flat list of every commit that happened, even if the commit originally happened on a separate branch.
This enables good interdiff review, so you can re-review just the new stuff in the new version of the commit and not the entire thing all over again.
In Gerrit, you commit every review, and the author has to edit individual commits to address them (using git rebase). This may sound PITA but it makes the history absolutely clean, and makes it easier for both reviewers and authors to review and address suggestions.
On Github, on the other hand, reviewing a large PR is just insanely hard. Making sure comment was addressed properly is hard as well, they can get lost in a sea of suggestions. They also become separate commits instead of being part of the commit itself. The commit should always been treated as unit of work rather than the branch.
It's equivalent to asking, "Why would you have more than one story in an epic (or task in a story)?".
It certainly puts pressure on the scope and quality of commits, but I think that's only undue for a short-lived project where you don't foresee a long period of maintenance. Consistently high quality commits with a clear scope is a godsend when you are investigating the history of a project. Some small pressure now is IMO better than greater pressure later when you are debugging an issue at three in the morning and scrolling through either a bunch of "fix stuff" commits or 1000+ line PR squashes.
You can do as many commits as you want locally. Then go back and squash them before pushing. I think that addresses all your points, if I am not mistaken.
The extra commits are just noise that make you think the original commit is a source of truth in a blame when it has been amended 3 times more in the same PR, but the link isn't apparent anymore.
Force pushing is bad to a published branch, not a feature branch (not that you really have force pushes in Gerrit anyway). There are versions of Gerrit tooling where you can have a branch as dirty as you want locally, but only the final aggregated change is visible for review of that's what you prefer too.
I think this is maybe what you’re asking about: with PRs, you often respond to feedback by adding new commits on to the PR. This is because code review is based on reviewing an entire branch. In a stacked diff based system, you respond to feedback by amending the commit. This is because reviews are tied to individual commits, not branches.
The reason people prefer this is that it keeps changes small and focused, and makes sure you have a high quality history. It also lets you assign different reviewers to different parts of your stack, which is helpful for all sorts of reasons. It also means that you can land earlier commits while waiting on review for the later commits, instead of holding it all up at once. Lots of stuff like this.
Integration into main ideally is squashed down to a single merge commit though.
It shouldn't matter how many commits a pr takes to from 0 to finished
a) Not create new API/commands on top of it. Everything works with the normal "git commit".
b) Progressively enhance the user experience. Each commit becomes a PR stacked atop each other. It auto-rebases if the base changes, and so on.
It uses a persistent changeid to model a change mutating over time, like Gerrit uses Change-Id in the description footer, and unlike git.
Jujutsu can be colocated with git and use .git as its backing store; every jj change revision is a git commit.
When you use jujutsu, you tend not to use branches any more, and think in terms of changes and chains of changes (i.e. stacked PRs, what Gerrit calls Relation Chains).
Jujutsu makes it very easy to work with a chain of changes (stacked PRs), letting you update commits in the middle and automatically rebasing the rest of the chain, without forcing you to interrupt work and resolve conflicts if there happen to be any (so, unlike git rebase -i with 'edit' on the commit you want to update).
IMO if you like the Gerrit workflow and the way it handles chained commits, if you switch to jj for two days of work, you'll never want to use git again.
I wrote it internally after struggling a lot with getting the relevant knowledge from the relevant authorities (Klabnik has the best resources but his writing seems to depend on you understanding abstract concepts before you grasp the practicality, which works for programming languages but less so for tools - which you want to "get out of the way").
in fact.. screw it... here: https://blog.dijit.sh/gerrit_with_jj/
There are also the "Mark as reviewed" checkboxes per file that can help you track what's been looked at.
Personally, I think jujutsu has already succeeded at becoming a "git killer" in terms of UX and adoption. It is compatible with git, so I'm never going back to using git directly.
A couple questions:
1) what's the name about? 2) does this get wicked messy if I'm the only one on my team using Maiao?
2. I don't think so. The main difference from maiao to other stacked diffs projects is that it _progressively enhances_ GitHub. At the end of the day you just get PRs with branch #3 -> branch #2 -> branch #1 -> main. So, a bit of automation and rebases to do this. Because teams rarely can choose their forge, the intent is to not force org-wide change — e.g., change the VCS to jj — nor introduce more API/UI surface. You can be the only one doing stacked diffs in your team. Nothing breaks.
Very cool stuff, will be trying it out
Basically it lets you treat the commits as part of the thing you are reviewing instead of just a minor detail that the UI doesn't care about very much.
The current UIs don't punish you for that as the reviewer mostly sees one final coherent change.
Edit: apparently stacked PRs on GH are older than I thought; the readme references a 2024 blog post about it.
In short: maiao supported stacked PRs on GH, before it existed as a feature :) Now that it's exists (beta), it simply does "progressive enhancement" and adds the PRs to the native stack. But you could still perfectly function without it. That's how maiao works on Codeberg, and Bitbucket, for instance.
GiLab has an interesting approach where they auto-stack up until 20 Merge Requests, if they're chained.
As they say in mtg, reading the card explains the card
I'll say from personal experience that Gerrit helped my team a lot, if for no other reason than enforcing a "one commit equals one change" model. Also, the commenting and reviewing experience was liked more in Gerrit than Github.
What's a Gerrit? (Looks it up)
Gerrit is based on Rietveld
What's a Rietveld? (Looks it up)
Rietvelt integrates with SVN
In contrast to Gerrit and Phabricator, it needs not "Change IDs" inserted in your commits (easier workflow just using git) and "just works" to review whole branches.
It seems to me that "1 PR = 1 commit = 1 review" and "stacked PRs" workflows are just workarounds for not properly having implemented that as Reviewable has. Am I not seeing something?
Reviewable's main drawback is being for Github only and not open source.
Gerrit/CodeApprove/Reviewable-style reviews are actually designed for exactly the scenario you're describing.
The thing you're missing is that it's helpful to see a diff view of, "What changed since my last review?"
If your review workflow is:
1. Junior engineer makes 15 commits to implement a feature in 300 LOC
2. Junior engineer sends you the PR for review
3. You review and send your notes to the engineer
4. Junior engineer makes 15 more commits and another 100 LOC churn, but PR is 350 LOC total diffs
At (4), the thing you probably want to see are the 100 LOC of diffs since step (3). I haven't tried this on GitHub for awhile, but last I checked, your options are to either view only diff of PR against main branch, view each of the 15 commits individually, or hand edit the URL to get the "what's changed since (3)?" view.
On Gerrit/CodeApprove/Reviewable, they all default to "what changed since I last reviewed?" and you comment on that diff rather than what's changed against the main branch, which is the default on GitHub.
It's hard to leave Gerrit after using it.
Then, when your senior developer is working on a new feature that requires some changes to adapt to a dependency upgrade, some refactoring, some forwards-and-backwards compatible database migrations, you'll appreciate a stack of discrete, clean, working, individually reviewable commits.