_Originally created by @sajolida on [#9174 (Redmine)](https://public-redmine-archive.tails.boum.org/code/issues/9174)_ # Rationale We want to migrate our blueprints out of our main website and in their own ikiwiki. This will allow us to: - Be able to push more documents to our blueprints (images, office documents, etc.) without polluting our main repo. - Lock down all web editing on our main website. - Allow more people to push changes to blueprints through Git if they prefer this to the web editor. - Maybe lower the amount of spam intrigeri and sajolida have to monitor and manually revert. - Maybe some day, host our website on servers that we don't trust to push to tails.git. See <https://lists.autistici.org/message/20150327.141615.36482193.en.html> # The plan - [x] Create a new GitLab project where this wiki will live - [x] Automate the migration of the contents - [x] Create a Git repo history that only contains blueprints - [x] Replace internal ikiwiki links to outside of `/blueprint/` with hard-coded links to our website - [x] Preserve internal wiki links - [x] Replace ikiwiki shortcuts with hard-coded links - [x] Turn `tails_ticket` into GitLab issue link syntax - [x] Convert tables - [x] `german_glossary.md` - [x] `user_survey/openpgp_and_pidgin.md` - [x] `veracrypt.md` - [x] Replace other ikiwiki-specific syntax - [x] `[[!inline ...]]` - [x] `[[!tag ...]]` - [x] `[[!map ...]]` - [x] `[[!meta ...]]` - [x] `[[!toggle ...]]` - [x] Create a wiki home page - differentiate archives from non-archived - [x] Ensure resulting navigation is good enough - [x] Customize sidebar: direct links to the most commonly used pages - [x] Prepare other migration steps - [x] Figure out what to do with `monthly_report/simplified.md` - [x] Prepare `puppet-tails` branch with redirections from `/blueprint/*` to GitLab wiki - [x] Prepare `gitlab-config` branch with production settings for the `tails/blueprints` project - give RW access to the wiki to relevant folks (*Developer* status) - make the GitLab project public - [x] Prepare `tails/tails` branch - [x] Replace ikiwiki internal links to blueprints with hard-coded links to GitLab wiki - [x] Freeze ikiwiki blueprints - [x] Disable editing in `ikiwiki.setup` - [x] Ask committers to not push changes via Git - [x] Migrate the contents - **Checkpoint** — after this point, contents start diverging and rolling back the migration becomes difficult & expensive - [x] Merge !323 - [x] Merge & deploy `gitlab-config` branch (tails/gitlab-config!14) - [x] Merge & deploy `puppet-tails` branch (tails/puppet-tails!38) - [x] Delete blueprints from `tails/tails` - [x] Ensure the website builds - [x] Redirect https://tails.boum.org/blueprint to GitLab wiki - [x] Delete blueprints-specific config from `ikiwiki*.setup` in `tails/tails` - [x] Delete blueprints-specific config from `ikiwiki.setup.erb` in `puppet-tails` - [x] Merge `master` into `stable` and `devel` - [x] Ensure `stable` and `devel` build - [x] Announce the end of the migration # Our options The options we've been considering so far are: - a dedicated ikiwiki instance (blueprints.tails.boum.org) - a GitLab wiki (<https://docs.gitlab.com/ce/user/project/wiki/> - a non-wiki Git repository hosted on GitLab - [rendered example](https://gitlab.tails.boum.org/tails/tails/-/blob/master/wiki/src/blueprint/migrate_blueprints.md) | | GitLab wiki | GitLab repo | ikiwiki | | -------- | ---------- |------------ | ------- | | Edit pages | what you would expect from a wiki in 2020 | similar to wiki | nerdy, lacks basic features, preview is painful | | Create a new page | prominent _New page_ button | + button when in a directory | cumbersome: create broken link then click it | | Delete a page | _Delete page_ button on the rendered page | _Delete_ button on the rendered page | yes, in the page editor | | Rename a page | prominent in the page editor | inside edit page | yes, in the page editor | | Markdown syntax | powerful | powerful | lacks basic features (e.g. tables) | | Links to GitLab issues, MRs, commits, etc. | great | good but lacks status info such as "(closed)" | mostly manual, lacks status info such as "(closed)" | | Links to other wiki pages | great | a bit cumbersome: has to use _file_ path instead of page name | great | | Page history | simple | slightly more complex than wiki | nerdy: external cgit or similar | | Search | default gitlab search | default gitlab search | poor | | Navigation | customizable sidebar, breadcrumbs, manual index pages | plain filesystem tree, breadcrumbs, manual index pages | breadcrumbs, customizable sidebar | | Attach files | _Attach a file_ in page editor | no | yes, in page editor | | Table of contents | yes | yes | yes | | Drafting design doc | requires replacing GitLab-specific syntax | requires replacing GitLab-specific syntax | Can be seamlessly moved to our design doc (it does not rely on GitLab-specific features) | | Preserving habits | Behaves like everything else in GitLab | Behaves like everything else in GitLab | Historical contributors are used to it (whether they like it or not, is another matter, but at least they don’t have to learn anything new). | | New contributors | This is what new contributors would expect / are used to | uncommon workflow | nerdy stuff | | Access control | same as our other GitLab stuff | same as our other GitLab stuff | has to be managed independently | | Migration cost | low | low | high | | Maintenance cost | none | none | moderate | # If we decide to use ikiwiki These subtasks assume we use a new, dedicated ikiwiki for blueprints. If we decide to instead use a GitLab wiki, they'll need to be adjusted: - sysadmin#9175 - sysadmin#9176 - sysadmin#9178 - sysadmin#9179 - sysadmin#9180 - sysadmin#9181 - tails/tails#9182