AGP 19: Documenting Aragon repository governance

[john-light]

AGP: 19
Title: Documenting Aragon repository governance
Author: John Light
Status: Draft
Created: 2018-06-18

Description

Each repository under the Aragon organization on GitHub (github.com/aragon) should have a GOVERNANCE.md file that documents the governance status and process of the repo. Information in this file should:

• Make clear who is the maintainer and who has commit access to the repository
• Document how and when current and past maintainers and those with push access gained their privileges
• Document how maintainer and push roles can be changed (or if they can’t be, state as much)
• This information is lightly documented in the wiki (see “Owned by” labels in http://wiki.aragon.one/dev/) but I think this could be formalized a bit to make it clearer.

Example

The GOVERNANCE.md file in a repo might look something like this:

Current maintainers

Alice (github.com/alice)

Current push access

• Alice (github.com/alice)
• Bob (github.com/bob)
• Carol (github.com/carol)

Changelog (from most recent)

• 2018-06-03 Alice (github.com/alice) gave push access to Carol (github.com/carol)
• 2018-05-01 Alice (github.com/alice) removed push access from Sarah (github.com/sarah)
• 2018-04-01 Alice (github.com/alice) removed push access from Eve (github.com/eve)
• 2018-04-01 Eve (github.com/eve) gave maintainer role to Alice (github.com/alice)
• 2018-03-01 Eve (github.com/eve) gave push access to Alice (github.com/alice)
• 2018-02-01 Eve (github.com/eve) gave push access to Bob (github.com/bob)
• 2018-01-01 Eve (github.com/eve) created repo on behalf of Aragon Foundation

Governance rules

• Maintainers of the repo are first appointed by the Aragon Foundation.
• Maintainers can appoint new maintainers and assign or revoke push access to the repo.
• The Aragon Foundation can override any decisions made by the maintainers.
• Forks of this repo are governed by the LICENSE.md file in this repo and whatever additional governance process is put in place by the maintainer of the forked repo.

CODEOWNERS (Optional, only if there is a CODEOWNERS file in the repo)

You can find the code owners for this repo in the CODEOWNERS.md file in this repo.

[0x-r4bbit]

Hi @john-light

I'm not sure if this proposal is still considered active as I've only seen reactions but no actual comments, however, there are some thoughts on this I'd like to leave here and please feel free to ignore them if they don't align with this proposal :)

Current commit access
Alice (github.com/alice)
Bob (github.com/bob)
Carol (github.com/carol)

• I think it's good to make clear who's "maintaining" the project so ppl know whom to reach out to if they want to contribute in some way.
• "Current commit access" should probably be reworded to "Push access" as everyone can commit on repository clones but only authorized identities can push back into upstream
• Usually read/write (or clone/push) access is controlled via GitHub Teams, so who ever has push access depends on what teams have push access and who's part of that team. Maybe it makes sense to just put a GitHub Team name in there instead? This way the governance file doesn't have to be touched all the time when teams change 👉🏼 Less maintenance work (cuz this has to be kept in sync manually otherwise)

Changelog (from most recent)

• Considering the points above, I'm not sure how much sense it makes to document permissions to push this way... also, I believe this gets easily out of hand as it would be tricky to always remember to update the governance file when those changes are made. However, if this really should go in there then maybe the next point might help with this.
• GitHub has an "Audit Log" which logs all of that stuff already. In terms of maintainability it might even make sense to semi-automate this and build a tool that updates the changelog on a regular bases, based on the organizations Audit Log, so maintainers won't have to remember to keep things in sync.

That's it. Again, those were just some thoughts that popped into my mind when I read this proposal, so feel free to ignore them if they don't make a lot of sense :)

Looking forward to your feedback!

[john-light]

Hi @PascalPrecht thanks for your feedback! Some replies:

I think it's good to make clear who's "maintaining" the project so ppl know whom to reach out to if they want to contribute in some way.

Totally, I have that here:

Current maintainers...

"Current commit access" should probably be reworded to "Push access" as everyone can commit on repository clones but only authorized identities can push back into upstream

I'm referring to the master branch, but I'm also no git expert so if "Push" is more accurate terminology then I am happy to accept this suggestion! (Other git experts out there have an opinion?)

Usually read/write (or clone/push) access is controlled via GitHub Teams, so who ever has push access depends on what teams have push access and who's part of that team. Maybe it makes sense to just put a GitHub Team name in there instead? This way the governance file doesn't have to be touched all the time when teams change 👉🏼 Less maintenance work (cuz this has to be kept in sync manually otherwise)

Great suggestion. I will look into whether team membership is/ can be made public so that we can maintain transparency with this method. Less work for equal output is a win!

Considering the points above, I'm not sure how much sense it makes to document permissions to push this way... also, I believe this gets easily out of hand as it would be tricky to always remember to update the governance file when those changes are made. However, if this really should go in there then maybe the next point might help with this.

GitHub has an "Audit Log" which logs all of that stuff already. In terms of maintainability it might even make sense to semi-automate this and build a tool that updates the changelog on a regular bases, based on the organizations Audit Log, so maintainers won't have to remember to keep things in sync.

Yes the idea is definitely to automate this as soon as possible. And if the Audit Log is/ can be made public then we can just link to that from this section instead of duplicating that information.

Thanks again!

[0x-r4bbit]

I'm referring to the master branch, but I'm also no git expert so if "Push" is more accurate terminology then I am happy to accept this suggestion!

I fully understand! So one of the things that comes by the nature of how Git repositories work and sometimes turns out to be a downside, is that there's no configurable restricted access over particular branches in a repository.

Every clone/fork of a repo is the whole thing (including branches and tags) at that point in time. There's no way one could say, only certain identities can commit into a master branch. If you clone a repo, it's yours. You can do with it whatever you want and in fact, nobody else even knows what you're doing until you try to push your changes back.

So it really boils down to whether someone has read/write access to a whole repository. :)

Anyways, I hope this makes sense!

[john-light]

Updated example with push language.

[sohkai]

We should also include CODEOWNERS in the governance process.

[0x-r4bbit]

@sohkai Wow, I had no idea such a thing existed! That's really useful, especially because it lets you define owners of particular branches and even file types (e.g. *.js files). Thank you for bringing this up!

[john-light]

@sohkai looking at the CODEOWNERS docs it seems that the purpose of the CODEOWNERS file is more narrow in scope than the GOVERNANCE file suggested here and also seems to inherit the governance rules of the repo itself:

The people you choose as code owners must have write permissions for the repository.

So while I think the CODEOWNERS file is a cool idea, I would leave it outside the scope of this AGP and the suggested GOVERNANCE file.

At the very least, we could perhaps add a "CODEOWNERS" section of the GOVERNANCE file and link to the CODEOWNERS file, if any. Something like:

CODEOWNERS

You can find the code owners for this repo in the CODEOWNERS.md file in this repo.

Then we could automate updating that section based on whether there is in fact a CODEOWNERS file in the repo. If there is none, then that section is deleted/ not added.

[john-light]

Related to this AGP: https://modeling-languages.com/add-a-governance-md-file-to-all-your-oss-projects/

[sohkai]

@john-light Agreed on adding a small section just to mention it.