TPA-RFC-77: style tweaks

Mostly consistency in capitalization, adding some links to related
issues, spell-checking and splitting long sentences.

See: team#41948

policy/tpa-rfc-77-puppet-merge.md

@@ -25,10 +25,10 @@ status: proposed
 
 This proposal is **not** about:
 
-- completely refactoring and deduplicating code, as that will be done step-by-step while we handle each services individually after the Puppet Server merge
-- ditching one way to store secrets in favor of another, as that will be done separately in the future, after both teams had the chance to experience Trocla and hiera-eyaml
-- tackling individual service merges, such as backups, dns, monitoring and firewall; these will be tackled individually once all infra is under one Puppet Server
-- applying new code standards everywhere; at most, we'll come up with general guidelines that could (maybe should) be used for new code and, in the future, for refactoring
+- Completely refactoring and deduplicating code, as that will be done step-by-step while we handle each services individually after the Puppet Server merge
+- Ditching one way to store secrets in favor of another, as that will be done separately in the future, after both teams had the chance to experience Trocla and hiera-eyaml
+- Tackling individual service merges, such as backups, dns, monitoring and firewall; these will be tackled individually once all infra is under one Puppet Server
+- Applying new code standards everywhere; at most, we'll come up with general guidelines that could (maybe should) be used for new code and, in the future, for refactoring
 
 ## Phase 1: Codebase preparation
 
@@ -42,53 +42,59 @@ This phase ensures that, once Tails code is copied to Tor's Puppet Control repo:
 ### Converge in structure
 
 - Tails:
-  - switch from Git submodules to using g10k in a monorepo
-  - remove ENC configuration, Tails don't really use it and the Puppet server switch will implement Tor's instead
-  - move node definitions under `manifests/nodes.pp` to roles
-  - switch to the directory structure used by Tor:
-    - move custom non-profile modules to `legacy/` (monitoring, apache, passenger), leave only 3rd party modules under `modules/`
-    - `hieradata` → `data`
-    - `profiles` → `site`
+  - Switch from Git submodules to using g10k in a monorepo
+  - Remove ENC configuration, Tails don't really use it and the Puppet server switch will implement Tor's instead
+  - Move node definitions under `manifests/nodes.pp` to roles
+  - Switch to the directory structure used by Tor:
+    - Move custom non-profile modules to `legacy/` (`monitoring`, `apache`, `passenger`), leave only 3rd party modules under `modules/`
+    - Rename `hieradata` to `data`
+    - Rename `profiles` to `site`
 
 ### Converge in substance
 
 - Tails:
-  - refactor the legacy apache and passenger modules out of existence
-  - rename all profiles from tails::profile to profile::tails
-  - ensure all exported resources' tags are prepended with tails_
+  - Refactor the legacy `apache` and `passenger` modules out of existence
+  - Rename all profiles from `tails::profile` to `profile::tails`
+  - Ensure all exported resources' tags are prefixed with tails_
 - Tor:
-  - install all 3rdparty modules that are used by Tails but not by Tor
-  - isolate all exported resources and collectors by using tags
-  - ensure there is a parameter to disable all 'base' functionality (i.e., nothing gets installed on a puppet node that is not explicitly included in the role)
-  - enforce signed commits
-  - ensure all private data is moved to trocla and publish the repo
-  - install eyaml, copy the eyaml keys from the Tails to the Tor puppet server, and adapt hiera.yaml to use them
+  - Install all `3rdparty` modules that are used by Tails but not by Tor
+  - Isolate all exported resources and collectors using tags
+  - Ensure there is a parameter to disable all 'base' functionality (i.e., nothing gets installed on a puppet node that is not explicitly included in the role)
+  - Enforce signed commits
+  - Ensure all private data is moved to Trocla and publish the repo ([tpo/tpa/team#29387](https://gitlab.torproject.org/tpo/tpa/team/-/issues/29387))
+  - Install EYAML, copy the EYAML keys from the Tails to the Tor puppet server, and adapt `hiera.yaml` to use them
 - Tor and Tails:
-  - upgrade 3rdparty modules to match versions
+  - Upgrade 3rdparty modules to match versions
 
 ## Phase 2: Puppet server switch
 
 This phase moves all nodes from one Puppet server to the other:
 
-- copy homebrew/legacy modules from Tails to Tor
-- copy roles and profiles from Tails to Tor
-- assign nodes to roles using the ENC
-- point Tails nodes to the Tor puppetserver
-- retire the Tails' Puppet server
+- Copy `legacy` modules from Tails to Tor
+- Copy roles and profiles from Tails to Tor
+- Assign nodes to roles using the ENC
+- Point Tails nodes to the Tor Puppet server
+- Retire the Tails' Puppet server
 
 ## Phase 3: Towards a more homogeneous codebase
 
 This phase paves the way towards a cleaner future:
 
-- one by one, for each profile in profile::tails
-  - move the profile to profile::, or
-  - merge the profile with an existing one in profile::
-- dedupe, refactor, cleanup, etc.
-- defining code standards (documentation, linting, pre-commit hooks, etc)
+- One by one, for each profile in `profile::tails`
+  - Move the profile to `profile` (without `::tails`), or
+  - Merge the profile with an existing one in `profile`
+- Deduplicate, refactor, cleanup, etc.
+- Defining code standards (documentation, linting, pre-commit hooks, etc)
 
 # Alternatives considered
 
-- [Migrate services to TPA before moving Puppet][]: some of the Tails services heavily depend on others and/or on the network setup (eg. Jenkins Agents on different machines talk to a Jenkins Orchestrator and a Gitolite server hosted on different VMs, then build nightly ISOs that are copied to the web VM and published over HTTP), and migrating these over to TPA's infra would be much more complex than just merging Puppet.
+- [Migrate services to TPA before moving Puppet][]: some of the Tails
+  services heavily depend on others and/or on the network setup. For
+  example, Jenkins Agents on different machines talk to a Jenkins
+  Orchestrator and a Gitolite server hosted on different VMs, then
+  build nightly ISOs that are copied to the web VM and published over
+  HTTP. Migrating all of these over to TPA's infra would be much more
+  complex than just merging Puppet.
 
 [Migrate services to TPA before moving Puppet]: https://gitlab.torproject.org/tpo/tpa/team/-/wikis/meeting/2024-11-11/#per-service-notes