From e5a7cf8de047bea573e4ce69b2bc5cc31509b19b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Mon, 15 Jun 2020 17:38:39 -0400
Subject: [PATCH] import more stuff from the nextcloud document, almost
complete
---
tsa/howto/gitlab.mdwn | 161 +++++++++++++++++++++++++++++++++++++++---
1 file changed, 151 insertions(+), 10 deletions(-)
diff --git a/tsa/howto/gitlab.mdwn b/tsa/howto/gitlab.mdwn
index d44b7f7e..e5e87d6a 100644
--- a/tsa/howto/gitlab.mdwn
+++ b/tsa/howto/gitlab.mdwn
@@ -161,6 +161,90 @@ The priority of those features would be:
Those are each large projects and will be undertaken at a later stage,
progressively.
+### Feature equivalence
+
+| Feature | Trac | GitLab | Comments |
+| ------- | ---- | ------ | -------- |
+| Ticket relations | parent/child | checklists | checklists show up as "X of Y tasks completed"¹ |
+| Milestones | yes | yes | |
+| Estimates | points/actual | estimation/spending | requires conversion from days to hours |
+| Private issues | no | yes | |
+| Issue subscription | RSS, email, ML | email | Trac sends email to trac-bugs |
+| User projects | no | yes | if users can create projects |
+| User registration | optional | disabled | ² |
+| Search | advanced | basic | no support for custom queries in GitLab³ |
+| Markup | WikiCreole | Markdown, GitHub-like | â´ |
+| IRC bot | yes | yes | zwiebelbot has to be patched, other bots to be deployed for notificationsâµ |
+| Git hosting | no, gitolite | yes, builtin | concerns about trusting GitLab with our code |
+| CI | no, Jenkins | yes, builtin | maybe in the future |
+| Upstream maintenance | slow | fast | Trac does not seem well maintained |
+| Wikis | one big wiki | per-project | ⶠ|
+| API | XML-RPC | REST, multiple clients | |
+| Javascript | optional | required | Drag-and-drop boards seem not to work but the list of issues still can be used. |
+
+Notes:
+
+ 1. Trac parent/child issue relationships have been converted into a
+ simple comment at the beginnning of the ticket linking to the
+ child/parent tickets. It was originally hoped to use the
+ "checklists" features but this was not implemented for lack of time.
+
+ 2. User registration is perfectly possible in GitLab but since GitLab
+ instances are frequently attacked by spammers, it is disabled
+ until we find an alternative. See missing features below for
+ details).
+
+ 3. GitLab, in particular, does not support inline searches, see
+ Missing features below for details.
+
+ 4. The wiki and issue formatting markup is different. Whereas Trac
+ uses [wiki formatting](https://trac.edgewall.org/wiki/WikiFormatting) inspired by old wikis like
+ [MoinMoin](https://moinmo.in/), a subset of the somewhat standard [Wikicreole](http://www.wikicreole.org/)
+ markup, GitLab uses [Markdown](https://en.wikipedia.org/wiki/Markdown), specifically their own [GitLab
+ version of markdown](https://gitlab.com/help/user/markdown) inspired by GitHub's markdown
+ extensions. The wiki and issues were automatically converted to
+ Markdown, but when you file new issues, you will need to use
+ Markdown, not Creole.
+
+ 5. specifically, zwiebelbot now knows about `foo#N` pointing to issue
+ N in project `foo` in GitLab. We need to update (or replace) the
+ `nsa` bot in `#tor-bots` to broadcast announcements to
+ projects. This could be done with the [KGB](https://salsa.debian.org/kgb-team/kgb/-/wikis/home) bot for which we
+ now have a [Puppet module](https://gitlab.com/shared-puppet-modules-group/kgb) so it could easily be deployed here
+
+ 6. because Trac does not allow users to create projects, we have
+ historically used one gigantic project for everything, which means
+ we had only one wiki. technically, Trac also supports one wiki per
+ project, but because project creation requires an admin
+ intervention, this never concretized.
+
+### Ticket fields equivalence
+
+| Trac | GitLab | Comments |
+| ---- | ------ | -------- |
+| id | id | keep the ticket id in legacy project, starts at 40000 in GitLab |
+| Summary | ? | unused? |
+| Reporter | Reporter | |
+| Description | Body | |
+| Type | Label | use templates to make sure those are filled |
+| Milestone | Milestone, Label | |
+| Version | Label | |
+| Keywords | Label | |
+| Points, in days | /estimate, in hours | requires conversion |
+| Actual points | /spending | |
+| Sponsor | Label | |
+| Priority | Board, Label | boards can sort issues instead of assigning arbitrary keywords |
+| Component | Subproject, Label | |
+| Severity | Label | mark only blocker issues to resolve |
+| Cc | @people | paid plans also have multiple assignees |
+| Parent issue | #reference | issue mentions and checklists |
+| Reviewer | Label | |
+| Attachements | Attachements, per comment | |
+| Status | Label | Kanban boards panels |
+
+Notice how the `Label` field is used as a fallback when no equivalent
+field exists.
+
### Missing features
GitLab does not provide one-to-one feature parity with Trac, but it
@@ -180,13 +264,11 @@ those tickets in the output.
[Kanban]: https://en.wikipedia.org/wiki/Kanban_(development)
-The **wiki and issue formatting is different** as well. Whereas Trac
-uses [wiki formatting](https://trac.edgewall.org/wiki/WikiFormatting) inspired by old wikis like [MoinMoin](https://moinmo.in/), a
-subset of the somewhat standard [Wikicreole](http://www.wikicreole.org/) markup, GitLab uses
-[Markdown](https://en.wikipedia.org/wiki/Markdown), specifically their own [GitLab version of markdown](https://gitlab.com/help/user/markdown)
-inspired by GitHub's markdown extensions. The wiki and issues were
-automatically converted to Markdown, but when you file new issues, you
-will need to use Markdown, not Creole.
+We do *not* have a **anonymous account** (AKA `cypherpunks`) for
+now. GitLab will be in **closed registration** for now, with users
+needing to request approval on a per-person basis for now. Eventually,
+we're going to consider other options to work around this (human)
+bottleneck.
### Interesting new features
@@ -287,7 +369,10 @@ around.
GitLab with the network team, considered as gitlab.torproject.net
but ultimately [abandoned](https://gitlab.torproject.org/tpo/tpa/services/-/issues/21840)
* 2019-02-28: gitlab-01 AKA dip.torproject.org test server setup
- ([issue 29400](https://gitlab.torproject.org/tpo/tpa/services/-/issues/29400))
+ ([issue 29400](https://gitlab.torproject.org/tpo/tpa/services/-/issues/29400)), following the [Brussels meeting](https://trac.torproject.org/projects/tor/wiki/org/meetings/2019BrusselsAdminTeamMinutes)
+ * 2019-07-17: GitLab discussed again at the [Stockholm meeting](https://gitlab.torproject.org/legacy/trac/-/wikis/org/meetings/2019Stockholm/Notes/InternalTooling)
+ * 2019-07-29: Formal proposal to deploy GitLab [sent to
+ tor-project](https://lists.torproject.org/pipermail/tor-project/2019-July/002407.html), no objection
* 2020-06-13 19:00UTC: [Trac readonly](https://lists.torproject.org/pipermail/tor-project/2020-June/002872.html)
* 2020-06-13 02:25UTC: Trac tickets migrated (32401 tickets, last
ticket id is [34451](https://bugs.torproject.org/34451), first GitLab legacy project ticket id is
@@ -387,24 +472,80 @@ rotation periods.
<!-- describe the overall project. should include a link to a ticket -->
<!-- that has a launch checklist -->
+The GitLab project at Tor has been a long time coming. If you look at
+the [history](#History) section above, you'll see it has been worked on since
+at least 2016, at which point an external server was setup for the
+"network team" to do code review. This server was ultimately retired.
+
+The current server has been worked on since 2019, with the master
+ticket, [issue 29400](https://gitlab.torproject.org/tpo/tpa/services/-/issues/29400), created in the footsteps of the [2019
+Brussels meeting](https://trac.torproject.org/projects/tor/wiki/org/meetings/2019BrusselsAdminTeamMinutes). The service launched some time in June 2020,
+with a full migration of Trac tickets.
+
## Goals
-<!-- include bugs to be fixed -->
### Must have
+ * replacement of the Trac issue tracking server
+ * rough equivalent of Trac features in GitLab
+
### Nice to have
+ * identical representation of Trac issues in GitLab, including proper
+ issue numbering
+
### Non-Goals
+ * replacement of Gitolite (git hosting)
+ * replacement of Gitweb (git hosting)
+ * replacement of Jenkins (CI)
+ * replacement of the static site hosting system
+
+Those are not part of the first phase of the project, but it is
+understood that if one of those features gets used more heavily in
+GitLab, the original service MUST be eventually migrated into GitLab
+and turned off. We do *not* want to run multiple similar services at
+the same time (for example run both gitolite and gitaly on all git
+repositories, or run Jenkins and GitLab runners).
+
## Approvals required
-<!-- for example, legal, "vegas", accounting, current maintainer -->
+
+The GitLab migration was approved at the 2019 Brussels dev meeting.
## Proposed Solution
+The solution to the "code review" and "project management" problems
+are to deploy a GitLab instance which does *not* aim at managing all
+source code, in the first stage.
+
## Cost
+Staff not evaluated.
+
+In terms of hardware, we start with a single virtual machine and agree
+that, in the worst case, we can throw a full Hetzner PX62-NVMe node at
+the problem (~70EUR/mth).
+
## Alternatives considered
+GitLab is such a broad project that multiple alternatives exist for
+different components:
+
+ * GitHub
+ * Pros:
+ * widely used in the open source community
+ * Good integration between ticketing system and code
+ * Cons
+ * It is hosted by a third party (Microsoft!)
+ * Closed source
+ * GitLab:
+ * Pros:
+ * Mostly free software
+ * Feature-rich
+ * Cons:
+ * Complex software, high maintenance
+ * "Opencore" - some interesting features are closed-source
+
### GitLab command line clients
If you want to do batch operations or integrations with GitLab, you
--
GitLab