On Fri, Aug 22 25 14:58, Robie Basak wrote:
> Hi Robert,
>
> 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.
Ack.
>> 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?
The main branch is protected and cannot be pushed into without an
approving review. That said, Sally (the other of the 'we' in my initial
email) and I have admin roles on the repo at this point, so,
theoretically, we could change the repo's settings -- this is a
temporary provision while the docs are heavily worked on.
This is mainly to be able to keep adding collaborators to the repo
(GitHub requires that anyone featured in the CODEOWNERS file is added as
a collaborator in the repo's settings).
The ACL includes a rule that requires someone (anyone) from the 'special'
teams to approve PRs that touch the CODEOWNERS file itself.
> 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.
We're open to suggestions in this regard. The repo itself was set up
(and is owned) by Canonical IS. I believe that to be a reasonable
choice, as well as a fallback once Sally and I relinquish the admin
roles.
>> 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?
If set up using the mechanism that IS has in place for syncing LP and
GH teams, this would be automatic.
> 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.
I'm talking to IS to see what we can come up with regarding the mapping.
In the meantime, I'd suggest we go the route of indiv. accounts in the
CODEOWNERS file. I realize that's a sub-optimal long-term solution, but
I think it's a good stop-gap while the larger docs set is WIP.
Robert
>> ...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
