Skip to content

Migrate our blueprints out of tails.git and tails.boum.org

Originally created by @sajolida on #9174 (Redmine)

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

  • Create a new GitLab project where this wiki will live
  • Automate the migration of the contents
    • Create a Git repo history that only contains blueprints
    • Replace internal ikiwiki links to outside of /blueprint/ with hard-coded links to our website
    • Preserve internal wiki links
    • Replace ikiwiki shortcuts with hard-coded links
    • Turn tails_ticket into GitLab issue link syntax
    • Convert tables
      • german_glossary.md
      • user_survey/openpgp_and_pidgin.md
      • veracrypt.md
    • Replace other ikiwiki-specific syntax
      • [[!inline ...]]
      • [[!tag ...]]
      • [[!map ...]]
      • [[!meta ...]]
      • [[!toggle ...]]
    • Create a wiki home page
      • differentiate archives from non-archived
  • Ensure resulting navigation is good enough
    • Customize sidebar: direct links to the most commonly used pages
  • Prepare other migration steps
    • Figure out what to do with monthly_report/simplified.md
    • Prepare puppet-tails branch with redirections from /blueprint/* to GitLab wiki
    • 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
    • Prepare tails/tails branch
      • Replace ikiwiki internal links to blueprints with hard-coded links to GitLab wiki
  • Freeze ikiwiki blueprints
    • Disable editing in ikiwiki.setup
    • Ask committers to not push changes via Git
  • Migrate the contents
  • Checkpoint — after this point, contents start diverging and rolling back the migration becomes difficult & expensive
  • Merge !323 (merged)
  • Merge & deploy gitlab-config branch (tails/gitlab-config!14)
  • Merge & deploy puppet-tails branch (puppet-tails!38 (merged))
  • Delete blueprints from tails/tails
  • Ensure the website builds
  • Redirect https://tails.boum.org/blueprint to GitLab wiki
  • Delete blueprints-specific config from ikiwiki*.setup in tails/tails
  • Delete blueprints-specific config from ikiwiki.setup.erb in puppet-tails
  • Merge master into stable and devel
  • Ensure stable and devel build
  • Announce the end of the migration

Our options

The options we've been considering so far are:

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:

Edited by intrigeri
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information