On Wed, Aug 20, 2025 at 12:16:00PM +0200, Robert Kratky wrote:
> As you may have noticed, these past few months we've been working on
> consolidating all Ubuntu project docs (i.e. 'how Ubuntu is made' kind of
> docs) in one place. This includes stuff from other docs sets (various
> packaging guides, the Ubuntu Maintainers Handbook), internal docs,
> people's heads, etc.
>
> The goal is to have all this guidance easily accessible, navigable, and
> under one umbrella, so that both new and existing contributors and
> maintainers have better experience. We've been publishing fortnightly
> updates on our progress on Ubuntu Discourse. The last one (which
> includes links to all previous updates) is at [1].
This sounds good to me. Thank you for driving this! I really appreciate
having people dedicated to looking after and improving our
documentation.
> The docs sources are in GitHub under the 'Ubuntu' org [2], and it's
> published through ReadTheDocs [3]. The URL is ugly now, but we'll change
> it to something like docs.ubuntu.com/project once it's less WIP.
>
> We'd like to include the SRU [4] and Governance docs [5] in that to
> streamline maintenance and also ensure the resulting project docs really
> do include all the docs.
Please could you ensure to preserve history, eg. with a merge commit? I
think the history of what rule or policy changed when is important to
preserve; this has been useful to understanding the past to make
decisions about the present.
> However, we understand both the Board and SRU require control over the
> content. That's perfectly understandable, and we have no intention of
> disrupting that.
>
> There are other such docs in the consolidated (GitHub) repo now: MIR and
> AA. In both cases, those teams want to have a final word, too. So, we
> set up a basic ACL using the standard CODEOWNERS file [6] (no PR that
> touches anything in 'their' part of the docs can be merged without their
> approval).
Who has permission to push to the main branch directly, or to change the
ACL?
Of course this is roughly equivalent to asking who has admin permission
on Launchpad (AIUI the answer is: Canonical IS and some Launchpad
developers and associated people). This isn't a problem per se; we
should make sure though that they understand their responsibilities in
delegating effective control to the relevant teams and avoid
overstepping. To help with this I think it's probably a good idea to
define this set of people and keep it small.
> This setup is what I'd like to offer the Board and SRU. I believe the
> case for consolidating all this content in one place is sound, and the
> CODEOWNERS setup ensures the content wouldn't be out of your team's
> control.
>
> The one potentially sticky point is that it's on GitHub, i.e. the
> involved people would need a GH account for the ACL to work. We can
> include people individually, which is what we've been doing so far.
> Special GitHub teams could also be set up for that purpose.
>
> (We've also been looking into auto-syncing LP -> GH teams, so this
> access control would continue to be automatically based on LP team
> membership...
I think it's important that friction to make changes remains low. We
must avoid creating "second class citizen" governance team members
because team membership changes haven't propogated. Please could you
ensure that whatever process you use, changes propagate without
intervention and without delay?
You'll presumably need a mapping from Launchpad accounts to GitHub
accounts. Maybe the Launchpad "social accounts" feature could be used
for this, like for Matrix. But then you'll need to ensure to propagate
both on Launchpad team membership changes as well as mapping changes,
and perhaps this needs some thought about validation.
> ...though there's still the thing that the service -- as it is
> available now -- is run by Canonical, so I'm not sure if that would be
> acceptable.)
This part is fine. The Ubuntu project trusts Canonical (amongst many
other things) to run its infrastructure. Launchpad is run by Canonical,
and that's considered acceptable :)
Thanks again for making our documentation better!
Robie
--
ubuntu-devel mailing list
ubuntu-devel@lists.ubuntu.com
Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/ubuntu-devel
