The Ubuntu Project docs effort is charging on. During the last two weeks, Sally has completed the migration of MIR (Main Inclusion Review) docs into the new repo. We also set up ACLs for the MIR team to allow them to control that content. Other than that, we continued to bring content over from the wiki and figuring out how best to structure the docs.
MIR docs
This has been the main theme of the (two-week) Pulse. @sally-makin did the majority of the heavy lifting, helped along by suggestions and reviews from @paelzer in particular. While we call it a “migration”, the content has also been significantly improved during the process.
This is the new entry point! Let us know what you think. Sally also created issues in the repo queue to mirror the docs-related MIR issues that existed in the old one. Overall, this has been a strong start, and big thanks to the MIR team for being first through the door!
ACLs
We also wanted to push the MIR docs into the new repo first in order to test-ride a basic ACL (access control list) implementation based on the standard CODEOWNERS file that can be added to repos. The MIR team, similarly to some other Ubuntu Project teams, needs to maintain control over their process docs.
This doesn’t mean it would be somehow closed off to public scrutiny or contribution suggestions, but given the potential sensitivity of the MIR decision-making process, the team needs to retain the last word on what the docs say. Other such teams include, for example, the SRU (Stable Release Updates) or the distro’s Technical Board.
Using CODEOWNERS, we set the ownership structure as follows (for the time being):
- The entirety of the repo owned by us, i.e. the docs people…
- …with the MIR content explicitly excepted from that
- The MIR content owned by the MIR team
- All changes to the CODEOWNERS file require an approval by someone from the MIR team, too
Of course, we also configured the repo to require PR approvals from respective content owners before merging to main.
This way, we believe we have a sensible and extendable ACL policy in place. Teams that require content ownership can have their docs hosted in the repo while retaining the necessary approval rights. Thus, we can move forward with consolidating all project guidance in one place while keeping teams happy about access arrangements, while still making it possible for contributors to propose changes to the content.
From a project governance perspective, this is crucial to ensure that either inadvertent or misguided edits are not made to docs that are used to maintain the integrity of the project’s procedures.
Glossary
We also went ahead and added a glossary page. Those of you familiar with the Packaging Guide might recognise it! It has originally been compiled by @dviererbe, @waveform, and others who have been working on bringing the Packaging Guide back from the dead. Now this glossary will serve as the project-wide reference.
We also added hover-over tooltips, so that when you hover your cursor over a term in the docs, it will show you the glossary definition. No need to leave the page you’re on!
If you’d like to contribute to this effort, the glossary is a perfect place to start that offers many opportunities for small, meaningful contributions (hint, hint ;))
Manpage links
Another neat feature we’ve borrowed from the Packaging Guide is the ability to refer to packages in the text with a manpage role, which automatically creates the link to the relevant manpage when the docs are built! No need to go hunting for the URL, or worry about updating it each time there’s a new release.
Wiki content migrated
We’ve brought over a number of pages from the old wiki that need some experienced eyes on. These are all in the staging area of the docs while we bring them up-to-date before their move to the docs.
What’s next?
- Document the ACL setup in the contributing section so contributors know what to expect.
- Migrate more existing content.
How to contribute/get involved
- Not all glossary terms have definitions yet - any contributions to missing definitions are welcome
- Feel free to take a look at any of the pages in the “staging” area of the docs and either submit issues or pull requests against them!
- We also have an issues list - if any of them interest you, and you’d like to tackle them, leave a comment on the issue so we can assign it to you.
- See our contributing guide for instructions on how to contribute.
