governance files: CODEOWNERS, CONTRIBUTING.md, and GOVERNANCE.md #49

andorsk · 2022-10-17T06:36:57Z

Initial governance files of CODEOWNERS, CONTRIBUTING.md, and GOVERNANCE.md. Related to issues:

#40
#39
#38
#46

These files are important for designating the repository management of the repo. A couple things:

I will copy things to the wiki after, that being said, the source of truth is the repo, NOT the wiki. If things ever get out of alignment, the repo should be the single source of truth.
I highlighted a few areas which are interesting/need some review.

andorsk · 2022-10-17T06:55:42Z

@a-fox can you take a look at this and give some feedback if possible.

andorsk · 2022-10-17T07:06:41Z

@talltree I'll copy the stuff over the wiki to make sure it's also documented there.

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

andorsk

Some comments and highlights.

andorsk · 2022-10-17T07:14:32Z

CODEOWNERS

+
+
+# These owners will be the default owners for everything in the repo.
+*       @talltree @wenjing


@talltree @wenjing i put you two as the default owners. But I'm not sure who the right people are here.

That's a good question. I would also add @darrellodonnell. We can always update this.

CONTRIBUTING.md

andorsk · 2022-10-17T07:15:10Z

CONTRIBUTING.md

+  for the change, the editor should follow the standard review process and refer
+  the PR in the issue
+
+### Editing Git process


Do we want to allow a branch directly off the repo? What about forking for changes?

PR's from forking should be allowed IMO for occasional contributors. Branching should be allowed for active contributors/editors. However, I would love to have as simple editing workflow as possible for active contributors.

We should discuss more on this.
I think our goal for Git-based document management should be:

Simple and concise way for non-git-savvy contributors to contribute changes (editor, minimal git-understanding required)

Have Issue & PR -based workflow for all changes

Enable editors with tools and workflows that contribute positively (i.e. help manage changes) and not negatively (too complex editing).

@a-fox I think the biggest thing is the process needs to be clear. There can't be a lot of decision making. I get being able to run a branch on the core repo sounds nice, but you run into issues like who can do it and under what circumstance, and then people get confused.

My suggestion:

Basic Options:

Fork the repo

Show a non-saavy git person how to use the Github UI to suggest a change.

Draft a PR and tag reviewer.

We should have a video for this, or some screenshots to make it easier.

Advanced Options:

IF you want to bring a repo locally, then document some ways. I've had a lot of success teaching people Github Desktop.

https://github.com/trustoverip/TechArch/blob/28ed180e011e45fbf503cb23e66416e305ef076d/CONTRIBUTING.md#basic-flow

GOVERNANCE.md

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

CONTRIBUTING.md

a-fox · 2022-10-17T14:04:35Z

CONTRIBUTING.md

+  for the change, the editor should follow the standard review process and refer
+  the PR in the issue
+
+### Editing Git process


PR's from forking should be allowed IMO for occasional contributors. Branching should be allowed for active contributors/editors. However, I would love to have as simple editing workflow as possible for active contributors.

We should discuss more on this.
I think our goal for Git-based document management should be:

Simple and concise way for non-git-savvy contributors to contribute changes (editor, minimal git-understanding required)

Have Issue & PR -based workflow for all changes

Enable editors with tools and workflows that contribute positively (i.e. help manage changes) and not negatively (too complex editing).

GOVERNANCE.md

Co-authored-by: Antti Kettunen <a-fox@users.noreply.github.com> Signed-off-by: Andor Kesselman <andor@henosisknot.com>

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

andorsk · 2022-10-19T06:28:21Z

Based on a conversation with @a-fox , we discussed prioritizing the focus of this PR as the following:

Make it as easy as possible for non-tech/Git saavy people to contribute to the TechArch repository. This is covered in the documentation. In particular, make sure to check out the CONTRIBUTING.md file. This should be in a state to shared for feedback by tomorrow, and it’ll be good to hear the rest of the community on how they feel about it as it currently stands.
In a separate PR: @a-fox will explore new ways which we can make it even easier for people to contribute.
@Antti Kettunen is leading that charge. He was going to try and make some proposals by Thursday.

@talltree @a-fox , please review the Governance and Contributing files, and review them to give feedback.

GOVERNANCE.md

andorsk · 2022-10-17T17:53:01Z

CONTRIBUTING.md

+  for the change, the editor should follow the standard review process and refer
+  the PR in the issue
+
+### Editing Git process


@a-fox I think the biggest thing is the process needs to be clear. There can't be a lot of decision making. I get being able to run a branch on the core repo sounds nice, but you run into issues like who can do it and under what circumstance, and then people get confused.

My suggestion:

Basic Options:

Fork the repo

Show a non-saavy git person how to use the Github UI to suggest a change.

Draft a PR and tag reviewer.

We should have a video for this, or some screenshots to make it easier.

Advanced Options:

IF you want to bring a repo locally, then document some ways. I've had a lot of success teaching people Github Desktop.

andorsk · 2022-10-17T18:05:59Z

CONTRIBUTING.md

+  for the change, the editor should follow the standard review process and refer
+  the PR in the issue
+
+### Editing Git process


https://github.com/trustoverip/TechArch/blob/28ed180e011e45fbf503cb23e66416e305ef076d/CONTRIBUTING.md#basic-flow

andorsk · 2022-10-19T06:32:42Z

CONTRIBUTING.md

+use to get going and to contribute to the repository *without ever touching the
+command line*.
+
+There is also a [Video Walkthrough](https://www.youtube.com/embed/3CuB0wdJaSU) 


Note: This is my youtube channel, which I used just for sample here. If ToIP has their own channel, I'm happy to put the video there, or we can remake it. I do think a video needs to be available though!

Yes, ToIP has a YouTube channel. @JFleenor has more info on that.

andorsk · 2022-10-19T06:37:25Z

Maybe need to put the https://github.com/andorsk/TechArch/tree/governance#contributing into the CONTRIBUTING.md file

andorsk · 2022-10-19T06:45:21Z

Note for the basic change flow ( non git loving users ), https://github.com/trustoverip/TechArch/blob/339dc1cf4bd0c7d226520dc963a1b9726937a020/CONTRIBUTING.md#basic-change-flow is where it’s documented.

To me, this is probably the highest priority to be sufficient before opening it up to the rest of the community, as this is where most the rubber will meet the road for a lot of people. @darrellodonnell can you please pay really close attention to this and see if the flow is reasonable for you and/or provide feedback if it's not satisfactory.

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

Added better flow description Signed-off-by: Andor Kesselman <andor@henosisknot.com>

Updates on roles and clarifications. Signed-off-by: Andor Kesselman <andor@henosisknot.com>

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

andorsk · 2022-10-19T07:28:39Z

@talltree @martchcl @darrellodonnell I've added you to the reviewers. Please go through this at your convenience and add commentary or even propose changes. You can click View File to look at the rendered .md file. Thanks!

GOVERNANCE.md

andorsk · 2022-10-25T12:40:20Z

@talltree where should the video in the Video Walkthrough: https://github.com/trustoverip/TechArch/blob/339dc1cf4bd0c7d226520dc963a1b9726937a020/CONTRIBUTING.md#basic-change-flow be hosted?

Signed-off-by: Andor Kesselman <andor@henosisknot.com> updated Governance file Signed-off-by: Andor Kesselman <andor@henosisknot.com>

a-fox · 2022-10-26T20:13:12Z

IMO this is ready for merge.

talltree

This is ready to merge. We can always tweak further as needed.

darrellodonnell · 2022-10-28T18:17:14Z

I am happy to see a last-call here. I am also testing my CLA integration!

This was linked to issues Oct 17, 2022

Provide CONTRIBUTOR.md file #38

Closed

Provide GOVERNANCE.md file #39

Closed

Define a set of rules and process for merging #40

Closed

Clarity on Assignee and Editor Process #46

Closed

andorsk self-assigned this Oct 17, 2022

andorsk added priority: high It is important for the group to resolve this issue soon. status: pr-in-progress The issue has been assigned and work is in progress. type: admin This issue requires an action by an admin. status: in-progress labels Oct 17, 2022

andorsk requested a review from a-fox October 17, 2022 06:55

This was referenced Oct 17, 2022

Clarity on Assignee and Editor Process #46

Closed

Provide CODEOWNERS file #43

Closed

Define a set of rules and process for merging #40

Closed

Provide CONTRIBUTOR.md file #38

Closed

Provide GOVERNANCE.md file #39

Closed

andorsk added 2 commits October 17, 2022 12:41

initial commit of governance files

b583bf4

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

fixed formatting

1399a1e

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

andorsk commented Oct 17, 2022

View reviewed changes

fixed some formatting of bullets

48c960e

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

a-fox reviewed Oct 17, 2022

View reviewed changes

andorsk and others added 2 commits October 17, 2022 23:16

some adjustments from PR review. still more to go

7ea2df0

Co-authored-by: Antti Kettunen <a-fox@users.noreply.github.com> Signed-off-by: Andor Kesselman <andor@henosisknot.com>

basic github flow better documented

28ed180

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

andorsk requested review from a-fox and talltree October 19, 2022 06:19

andorsk requested review from darrellodonnell and martchcl October 19, 2022 06:29

andorsk commented Oct 19, 2022

View reviewed changes

andorsk removed the status: in-progress label Oct 19, 2022

andorsk added 4 commits October 19, 2022 12:56

updated contribution guide

35f68b5

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

Update CONTRIBUTING.md

b3c438c

Added better flow description Signed-off-by: Andor Kesselman <andor@henosisknot.com>

Update GOVERNANCE.md

a137941

Updates on roles and clarifications. Signed-off-by: Andor Kesselman <andor@henosisknot.com>

Update CONTRIBUTING.md

e6ea772

Signed-off-by: Andor Kesselman <andor@henosisknot.com>

a-fox reviewed Oct 20, 2022

View reviewed changes

GOVERNANCE.md Outdated Show resolved Hide resolved

GOVERNANCE.md Outdated Show resolved Hide resolved

andorsk requested a review from a-fox October 25, 2022 12:39

andorsk marked this pull request as ready for review October 25, 2022 12:46

updated Governmance doc based on feedback

c3c5644

Signed-off-by: Andor Kesselman <andor@henosisknot.com> updated Governance file Signed-off-by: Andor Kesselman <andor@henosisknot.com>

a-fox approved these changes Oct 26, 2022

View reviewed changes

a-fox added status: pr-accepted The issue is linked to a PR that has been accepted and is waiting for merge. and removed status: pr-in-progress The issue has been assigned and work is in progress. labels Oct 26, 2022

This was linked to issues Oct 26, 2022

Provide Access Controls To Maintainers #45

Closed

Provide CODEOWNERS file #43

Closed

talltree approved these changes Oct 27, 2022

View reviewed changes

andorsk added status: last-call Issue has been resolved by a PR and is now in 5 day last call. and removed status: pr-accepted The issue is linked to a PR that has been accepted and is waiting for merge. labels Oct 27, 2022

andorsk merged commit 64abad1 into trustoverip:main Nov 2, 2022

andorsk deleted the governance branch November 2, 2022 11:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

governance files: CODEOWNERS, CONTRIBUTING.md, and GOVERNANCE.md #49

governance files: CODEOWNERS, CONTRIBUTING.md, and GOVERNANCE.md #49

andorsk commented Oct 17, 2022 •

edited

andorsk commented Oct 17, 2022

andorsk commented Oct 17, 2022

andorsk left a comment

andorsk Oct 17, 2022

talltree Oct 27, 2022

andorsk Oct 17, 2022

a-fox Oct 17, 2022

andorsk Oct 17, 2022

andorsk Oct 17, 2022

a-fox Oct 17, 2022

andorsk commented Oct 19, 2022

andorsk Oct 17, 2022

andorsk Oct 17, 2022

andorsk Oct 19, 2022

talltree Oct 27, 2022

andorsk commented Oct 19, 2022

andorsk commented Oct 19, 2022

andorsk commented Oct 19, 2022

andorsk commented Oct 25, 2022

a-fox commented Oct 26, 2022

talltree left a comment

darrellodonnell commented Oct 28, 2022



		# These owners will be the default owners for everything in the repo.
		* @talltree @wenjing

governance files: CODEOWNERS, CONTRIBUTING.md, and GOVERNANCE.md #49

governance files: CODEOWNERS, CONTRIBUTING.md, and GOVERNANCE.md #49

Conversation

andorsk commented Oct 17, 2022 • edited

andorsk commented Oct 17, 2022

andorsk commented Oct 17, 2022

andorsk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Basic Options:

Advanced Options:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andorsk commented Oct 19, 2022

Choose a reason for hiding this comment

Basic Options:

Advanced Options:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andorsk commented Oct 19, 2022

andorsk commented Oct 19, 2022

andorsk commented Oct 19, 2022

andorsk commented Oct 25, 2022

a-fox commented Oct 26, 2022

talltree left a comment

Choose a reason for hiding this comment

darrellodonnell commented Oct 28, 2022

andorsk commented Oct 17, 2022 •

edited