From 3ab65af9dcd4a5f56db10f8e1252c3b3737ced2f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Tue, 7 Nov 2023 12:49:42 -0500
Subject: [PATCH] expand problem statment, split proposal into potential
See tpo/tpa/team#40909 tpo/community/hackweek#26
---
policy/tpa-rfc-38-new-wiki-service.md | 44 ++++++++++++++++++++-------
1 file changed, 33 insertions(+), 11 deletions(-)
diff --git a/policy/tpa-rfc-38-new-wiki-service.md b/policy/tpa-rfc-38-new-wiki-service.md
index a058974d..b357dc1c 100644
--- a/policy/tpa-rfc-38-new-wiki-service.md
+++ b/policy/tpa-rfc-38-new-wiki-service.md
@@ -4,23 +4,37 @@ title: TPA-RFC-38: Setting Up a Wiki Service
[[_TOC_]]
-Summary: This RFC aims to identify problems with our current gitlab wikis, and the best solution for those issues.
+Summary: This RFC aims to identify problems with our current gitlab
+wikis, and the best solution for those issues.
# Background
-Currently, our projects that require a wiki use gitlab wikis. Gitlab wikis are rendered with [gollum](https://github.com/gollum/gollum), and editing is controlled by gitlab's permission system.
+Currently, our projects that require a wiki use GitLab wikis. GitLab
+wikis are rendered with a fork of [gollum](https://github.com/gollum/gollum), and editing is
+controlled by GitLab's permission system.
-The problem: gitlab's permission system only allows repo maintainers to edit wiki pages, meaning that users (anonymous or signed in) don't have the permissions required to actually edit the the wiki pages. This has lead the TPA team to create a separate tpo/tpa/wiki repo so that people without edit permission can at least propose edits for TPA maintainers to accept.
+## Problem statement
-# Proposal
+GitLab's permission system only allows maintainers to edit wiki pages,
+meaning that normal users (anonymous or signed in) don't have the
+permissions required to actually edit the wiki pages.
-The easiest solution to gitlab's permission issues is to use a wiki service separately from gitlab. This wiki service can be one that we host, or a service hosted for us by another organization.
+One solution adopted by TPA was to create a separate [wiki-replica
+repository](https://gitlab.torproject.org/tpo/tpa/wiki-replica/) so that people without edit permission can at least
+propose edits for TPA maintainers to accept. The problem with that
+approach is that it's done through a merge request workflow which adds
+much more friction to the editing process, so much that the result
+cannot really be called a wiki anymore.
## Goals
+The goals of this proposal are as follows:
+
* Identify requirements for a wiki service
-* Find a wiki service that fits these requirements
-* Install a new TPA-managed server to host the wiki, or find an organization to host it for us
+* Proposal modifications or a new implementation of the wiki service
+ to fits these requirements
+
+## Requirements
### Must have
@@ -28,7 +42,7 @@ The easiest solution to gitlab's permission issues is to use a wiki service sepa
* Wiki must have a search function
* Users should be able to read and edit pages over a hidden service
* High-availablity for TPA documentation: If the wiki ever goes down, TPA should not be locked out of the docs on how to recover the wiki
-* Clear transition plan from gitlab to this new wiki
+* Clear transition plan from GitLab to this new wiki
* Must be able to use current markup as-is, or be able to convert to a new syntax (with pandoc/sed script/etc.)
* Folder structure: current GitLab wikis have a page/subpage structure (e.g. TPA's `howto/` has all the howto, `service/` has all the service documentation, etc) which need to be implemented as well, this includes having "breadcrumbs" to walk back up the hierarchy, or (ideally) automatic listing of sub-pages
* Single dynamic site, if not static (e.g. we have a single MediaWiki or Dokuwiki, not one MediaWiki per team), rationale is static sites can be archived and not maintained in the long term, while dynamic applications need constant monitoring and maintenance to function properly, so we need to reduce the maintenance burden
@@ -39,7 +53,7 @@ The easiest solution to gitlab's permission issues is to use a wiki service sepa
* example: `/tpo/tpa/wiki_page_1`, `/tpo/core/tor/wiki_page_2` or Mediawiki's namespace systems where each team could have their own namespace (e.g. TPA: Anti-censorship: Community: etc)
* search must apply across namespaces
* integration with anonticket
-* integration with existing systems (gitlab, ldap, etc) as an identity provider
+* integration with existing systems (GitLab, ldap, etc) as an identity provider
* Support offline reading, and batching edits until a connection is restored (i.e. with git)
### Non-Goals
@@ -48,16 +62,24 @@ The easiest solution to gitlab's permission issues is to use a wiki service sepa
* confidential content: we put private content in Nextcloud (eg. TPI folder)
* software-specific documentation: e.g. stem.tpo, arti, ctor documentation (those use their own build systems like a static site generator), we might still want to recommend a single program for documentation (e.g. settle on mkdocs or hugo or lektor)
+# Proposals
+
+## Separate wiki service
+
+The easiest solution to GitLab's permission issues is to use a wiki
+service separately from GitLab. This wiki service can be one that we
+host, or a service hosted for us by another organization.
+
# Examples or Personas
Examples:
* bob: a non-technical person who wants to fix some typos and add some resources to a wiki page
- * with current wiki: bob needs to make a gitlab account, and be given developer permissions to the wiki repo (unlikely). alternatively, bob can open a ticket with the proposed changes, and hope a developer gets around to making them. if the wiki has a wiki-replica repo (i.e. like <https://gitlab.torproject.org/tpo/tpa/wiki-replica/>) then bob could also `git clone` the wiki, make the changes, and then create a PR. bob is unlikely to want to go through such a hassle, and will probably just not contribute
+ * with current wiki: bob needs to make a GitLab account, and be given developer permissions to the wiki repo (unlikely). alternatively, bob can open a ticket with the proposed changes, and hope a developer gets around to making them. if the wiki has a wiki-replica repo (i.e. like <https://gitlab.torproject.org/tpo/tpa/wiki-replica/>) then bob could also `git clone` the wiki, make the changes, and then create a PR. bob is unlikely to want to go through such a hassle, and will probably just not contribute
* with a new wiki system fulfilling the "must-have" goals: bob only needs to make a wiki account before being able to edit a wiki page
* alice: a developer who helps maintain a TPO repository
* with current wiki: alice can edit any wiki they have permissions for. however if alice wants to edit a wiki they don't have permission for, they will need to go through the same ticket/PR hassle as bob
- * with new wiki: alice will need to make a wiki account in addition to their gitlab account, but will be able to edit any page afterward
+ * with new wiki: alice will need to make a wiki account in addition to their GitLab account, but will be able to edit any page afterward
* anonymous cypherpunk: a person who wants to contribute to a wiki anonymously
* with current wiki: the cypherpunk will need to follow the same procedure as bob
* with new wiki: with only the must-have features, cypherpunks can only contribute pseudonymously. if the new wiki supports anonymous contributions, cypherpunks will have no barrier to contribution.
--
GitLab