Feature #15878: Switch to GitLab
Evaluate moving to GitLab for merge requests
We've added #14516 to our 2018 roadmap. I think this ticket is strongly related but it's too premature to be part of that roadmap item, so let's track it separately.
A few observations lead me to create this ticket:
- My experience welcoming new Tails contributors: we spend lots of time teaching new contributors how we use Redmine for submitting proposed changes. Symmetrically, given the amount of questions they ask and mistakes they do, it's clear that new contributors spend lots of time learning our workflow. I suspect this requirement raises the bar to a point that discourages some potential contributors who would be happy to fix a small bug or a couple typos, but are not ready to learn a workflow that they will have no use for anywhere else.
- My experience as a drive-by contributor elsewhere: as a free software user, pretty often I notice a small bug or typo that I could very easily fix. The chances that I actually submit a fix depends in great part on whether the affected project uses a well-known workflow. If it does, then generally I'll bother clicking a "Fork" button and submitting a merge request, e.g. https://github.com/ModernPGP/modernpgp.github.io/pull/9. If it doesn't, then generally I'll be lazy and give up. I suspect many people act similarly but I have no data to back this guess. Nowadays, a "well-known workflow" basically means a GitHub or GitLab web interface; using github.com or gitlab.com eases things even more for people who already have an account there, but IMO the need for creating an account is not that much of a problem as long as one knows they'll be at ease in the interface once logged in.
- Modern web-based merge request workflows provide a better UX for reviewers and contributors. I've been using GitLab more and more for other projects and some features are life changers in my experience:
- inline commenting on the specific piece of code one is reviewing and direct access to the submitted code from the same interface where the merge request is tracked, regardless of the status of the submitter (in our Redmine we have a list of commits but that only works if the submitter flagged them appropriately and has commit access to our official repo)
- a concept of having N open "discussions" on a merge request, that can be "resolved": compared to the linear list of comments without metadata that we have on Redmine, it makes it much easier to know what's left to address, because whatever has already reached a conclusion is hidden by default
- A great lot of people still prefer using a Terminal as much as they can but I'm also convinced that this set of people is getting more and more marginal, so probably we should not optimize our contributors workflow for them: our future new contributors are much more likely to be at ease with GitLab or GitHub than with our current workflow. Anyway, one can talk with GitLab using email.
So far so good. I'll ignore GitHub as I'm sure a proposal to move there would never reach consensus in our community so I'll focus on GitLab.
The problem is, these tools perform optimally when one uses them for issue tracking as well as merge requests. There are some options to integrate Redmine issue tracking with GitLab merge requests, but I don't think this combination would give us the advantages we're looking for in terms of improving new and current contributors experience: current contributors would have to learn GitLab, new contributors would have to learn Redmine, and everyone would still have to gain and maintain knowledge about a weird workflow nobody else uses.
GitLab's issue tracking has a very different set of features from Redmine's. It may be too limited for our needs even if it's improving (e.g. GNOME successfully got some features released in the "community" open souce version of GitLab, that were previously available only in the "enterprise" proprietary version). E.g. relationships between issues is not in the free software version (upstream bug), the set of metadata available for issues + the lack of complex search queries may prevent us from doing the kind of fancy stuff we've got used to on Redmine. So likely our most involved contributors would need to adapt a lot to the new set of features and concepts, in particular when working on, or managing, a large project. See for example how GNOME uses it.
- List user stories that Redmine currently satisfies and try to find how it could work with GitLab.
- Consider installing Redmine plugins that enable a GitLab-like workflow: free-form tagging (labels in GitLab-speak) instead of hard-coded custom fields / "blocks: core work XYZ: YYYYQN", checklists ("task list" in GitLab-speak) instead of subtasks. This would allow some of our teams to experiment with this workflow.
- Wait a bit. Moving won't happen in 2018 anyway and it would be good to see how GitLab fares for other projects like GNOME and Debian (although Debian won't use issue tracking).
- GNOME's tracker bug for upstream GitLab
Branch submit & review: make room for doing reviews on Salsa (refs: #15186).
Some teams want to experiment and start using GitLab for code reviews,
let's allow it and see how it goes.
Recommend forking Git on Salsa for "code" work (refs: #15186).
- Salsa because we have merge requests enabled there,
while we don't have them on gitlab.com (both on purpose).
- Only for "code" work: for now, only the FT is ready to deal
with merge requests sent on GitLab.
Document where to push "code" branches for review (refs: #15186).
Let's not implicitly suggest one can push directly to our repository on Salsa:
it's meant to be a read-only mirror of our canonical repo, and any changes made
directly on Salsa will be overwritten next time someone pushes anything to the
#8 Updated by segfault about 1 year ago
- Merge requests and GitLab CI are awesome, I think it's crazy we don't use them yet
- I do miss subtasks in GitLab, it makes it harder to split an issue into smaller tasks and there is no good overview for them
- I also miss the "blocked by" relationship, although less than the subtasks
=> I think we should start using GitLab merge requests and CI ASAP, but maybe still use redmine for the tickets.
- Type of work changed from Research to Test
- Our doc for "code" contributions suggests using MRs on Debian's GitLab (aka. Salsa). The FT is experimenting with this workflow internally as well.
- Our other contribution docs don't mention Salsa at all and still suggest the previous workflow (fork on gitlab.com and point the Redmine ticket to your branch); we can change this once we've dealt with any critical issue raised by the ongoing experiments and taught all Tails committers how to handle MRs on GitLab.
tailsproject on Salsa is minimally integrated with Redmine: a #NNN link on Salsa points to the relevant Redmine ticket.
Here's a first batch:
- 35 MRs were merged since we started this experiment ~7 months ago.
- On 2019-09-01, I asked feedback to the FT about this by the end of October. No reply so far. I've pinged the thread, with an updated deadline (end of this week). I'll report back here if I receive such feedback.
- I've heard enthusiastic feedback about the ability to comment on specific lines while reviewing.
- I've heard feedback about not seeing much benefit compared to the Redmine way of doing reviews. For context, this was about a rather small documentation branch.
- It's now clear to me that we need at least pointers to the relevant GitLab MR documentation: we should not take for granted that everyone is already used to GitHub/GitLab PR/MR workflows and web UIs. I've filed #17226 to ensure this is not forgotten by the folks who'll implement the migration.
- There's been some confusion caused by the current non-standard setup where the repo hosted on Salsa is not the canonical one, but a mirror one should not push to. These problems will not exist as long as the canonical copy of our repositories live on GitLab, so IMO these are strong points in favor of doing that.
- One aspect that was initially unclear to one person (i.e. where should follow-up commits be pushed) was promptly clarified, but further misunderstandings arose later in the conversation. For details, see the full discussion.
- There's been lots of confusion, for several people, caused by the fact that Salsa shows all pushes as made by yours truly, regardless of who actually pushed. That's because I'm the one who has set up the deployment key that's used to do the mirror synchronization.
- Through this experiment, I've learnt that one can comment on a commit on GitLab (I had no idea). But somehow the resulting discussion seems to have a different behavior wrt. notifications than a discussion happening on a MR: it looks like there's no concept of "participant". This resulted in someone missing a reply to a comment of theirs. I have no idea what's the deal here. I hope that documentation about MRs will help folks comment on the MR instead of on commits (especially commits that are not part of the MR, like in this case), which will avoid this kind of trouble. For details, see the full discussion.
- The FT has not used GitLab MRs much after the initial excitement, apart of for a few branches that were bigger than average and could truly benefit from GitLab's inline review facilities. I guess this can be explained by a combination of three factors:
- Most of our branches are tiny, simple, and get merged with no comment whatsoever by the reviewer. So most of the time, inline comments during code review would not be used. The only benefit we would get is the web UI to inspect the diffs and commits, but since at the end of the day one currently needs to merge via the command line, oh well, one can as well review on the command line.
- Most of our branches are about a Redmine ticket, so to use a MR, one needs to do extra paperwork. So unless the benefit of doing so is clear (not the case most of the time as said above), understandably we don't bother. The need for extra paperwork will vanish once our issues are tracked in GitLab.
- The FT already has a hard time to keep track of Redmine issues that need validation. Having to also monitor the MRs on Salsa requires more busywork, which is not exactly motivating.
- The feature of having N open "discussions" on a merge request, that can be "resolved" (as opposed to the linear list of comments without metadata that we have on Redmine, which makes long discussions harder to follow than they could be), was not used consistently: the default being to simply add a comment to the pile, folks who were not already used to GitLab tended to do that, including in cases where they should really have started a discussion. I trust this can be solved by a combination of documentation, learning by example, and gentle mentoring as folks get started with GitLab. Note that if that does not get solved, the end result is just as bad, and no worse, than what we have on Redmine.
I'll translate the take aways of this experiment into clear requirements/specifications for the folks who will implement our migration to GitLab.