Governance documents need source control

[markwhiting]

The problem

The governance documents we have collectively authored over the past few months are on google docs, where they are not intuitive to locate and where the process of robustly tracking changes is arduous.

My proposal

I propose to make markdown versions of each of our collectively authored governance documents and host them in a GitHub repository where anyone from the collective leverage them and propose changes to them through a formal process.

The documents included would be (with preliminary markdown conversions for some):

1. Governance Process: Stanford Crowd Research Collective → preliminary Markdown version
2. Operational Guide: Stanford Crowd Research Collective → preliminary Markdown version
3. Operational group membership: Stanford Crowd Research Collective → preliminary Markdown version
4. Code of conduct (once the document has been finalized)

---

This was imported from crowdresearch/daemo#1032 and the links were updated.

---

Edited to include the following added details:

Implications

The implications of this proposal are that we will:

1. have a public record of what we have agreed upon that is managed in a public and transparent manner as these documents evolve
2. have a formal way to modify these documents, e.g. proposal → pull request
3. have a structure for us to evolve these and other documents we use for governance

Attribution

The person who added the proposal to GitHub is Mark Whiting (markwhiting here and on slack)

The documents being added by this proposal were authored by the Crowd research collective over the course of the past several months.

Note: the name(s) in this section are not an indication that the person came up with this idea, unless and until explicitly and clearly mentioned.

---

Use comments to share your response or use emoji 👍 to show your support. To officially join in, comment I will help. To break consensus, comment using this template. To find out more about this process, read the how-to.

[neilthemathguy]

I agree with you about the need for versioning, but I’m a little confused here. Could you help me understand ---

1. Are you saying that these documents and repository does not exist and we need to create it from scratch?
2. What are the roles that should exist in such a repository?
3. Did we discuss how and whom to assign them?
4. Irrespective of above, do you think this or any other proposals submitted this week follow the template decided for the proposal?
5. Do you think this proposal complies with the established governance process?

In order to make a judgement about the proposal #2, I'll need above information.

[markwhiting]

@neilthemathguy thanks and here are some thoughts on your questions:

1. They did not exist in a repository. I have created test files to ensure that the markdown looks ok. It now does, which required a few minor changes in order to comply with Github's markdown spec. (e.g. no nested numbering).
2. We have not specified this. Because of the nature of our governance, where any community member can take part, it seems that ideally we would give all the community members write access.
3. No, but we should. Formalizing these things is part of adopting our governance mechanism.
4. The proposal template is intended to execute the stipulations of the governance documents. It is, itself, subject to iteration as we find better ways to scaffold people's proposal writing.
5. In so far as it adheres to the template.

[neilthemathguy]

Thanks!

They did not exist in a repository. I have created test files to ensure that the markdown looks ok. It now does, which required a few minor changes in order to comply with Github's markdown spec. (e.g. no nested numbering).

These documents, in fact the entire folder, already exists in the repository Here are the links https://github.com/crowdresearch/collective/blob/master/governance/ .

As per governance process (excerpt below), the changes do not take effect before proposal gets approved.

”No changes are made without a proposal, irrespective of how urgent or important it is — see blanket approvals for specific exceptions.”

We have not specified this. Because of the nature of our governance, where any community member can take part, it seems that ideally we would give all the community members write access.

If we didn't specify this then how do we have OWNERs for the repository? And how did we decide who should give access to others?

The proposal template is intended to execute the stipulations of the governance documents. It is, itself, subject to iteration as we find better ways to scaffold people's proposal writing.

My point is many proposals do not follow the proposal template highlighted in the governance document

https://github.com/crowdresearch/collective/blob/master/governance/process.md#proposal-process

Title
Name and Slack username of the person or people who created the proposal
Proposal details: 1) What problem is being solved? If feasible, specific evidence or examples (e.g., screen shots, data) in support of the understanding of the problem. 2) Short-term (and, if relevant, long-term) implications of executing this proposal
A thread containing the names of the Collective members engaged in the proposal's consensus process, and their reasons for support or non-support
Formal statement of anybody breaking consensus, rejoining the consensus, or standing by
Links to any relevant materials regarding the proposal's execution after it is approved, for example pull requests
Names and comments from any quality control reviewers
State of the proposal: active, approved, declined, voting
New proposals must also be cross-posted to the Collective's Slack space.

[markwhiting]

Yes, I created that folder to test it out based on this proposal. Before that I had created gists of those documents as part of this proposal. The gists are still on my account but I linked these ones because I thought it would be easier to have links that would not need to change.

I don't think you can have a repository without an owner. Explicitly, the aim of this would be to make it so that anyone in our community can completely use our governance mechanism. I'm happy to make that explicit in this proposal.

The point about template usage seems like it might be better addressed in a separate discussion or as part of a proposal. Are there any specific concerns you think should be addressed or updated in the issue template to better reflect this? Also, are there any scaffolds you think we can put in place to ensure people adhere to the template suitably?

[mbernst]

Good point, I'm going to dig in here to see what seems to be missing:

Title

Exists, woo.

Name and Slack username of the person or people who created the proposal

GitHub adds the name, but not the Slack username, so we should change the template to ensure people list their Slack username.

1. What problem is being solved? If feasible, specific evidence or examples (e.g., screen shots, data) in support of the understanding of the problem.

I think this exists in the template, but it would be good to include an explicit nudge for the "specific evidence or examples (e.g., screen shots, data) in support of the understanding of the problem" in the proposal template if it's not there.

2. Short-term (and, if relevant, long-term) implications of executing this proposal

This doesn't seem to be there yet, but I might be missing it.

A thread containing the names of the Collective members engaged in the proposal's consensus process, and their reasons for support or non-support

GitHub gives us that for free, woo. 👍 s or comments indicate support, and comments indicate non-support.

Formal statement of anybody breaking consensus, rejoining the consensus, or standing by

This exists for breaking consensus. Are there templates for rejoining or standing by? (To be clear, I don't think we're missing anything here yet, but it would be nice to have them.)

Links to any relevant materials regarding the proposal's execution after it is approved, for example pull requests

GitHub should give us that for free I think/hope

Names and comments from any quality control reviewers

This will presumably go into the thread. We presumably will need a response template for quality reviewers to use, or maybe just "lgtm".

State of the proposal: active, approved, declined, voting

I think Mark is currently wizard-of-oz'ing this. All proposals are currently active right now.

New proposals must also be cross-posted to the Collective's Slack space.

This is happening via the #updates channel is Slack. I would love to see a proposal with a better way of doing this integration. (For example, all new proposals and all comments on proposals currently go into one place, making things a bit messy.)

[markwhiting]

That looks right @mbernst. The short and longterm implications are mentioend in the proposal section of the template. But it could be made stronger.

[shirishgoyal]

I would love to see a proposal with a better way of doing this integration. (For example, all new proposals and all comments on proposals currently go into one place, making things a bit messy.)

We can tweak settings for github plugin in Slack to show specific items in Slack like new issues, comments , changes etc. Maybe anyone with Slack admin rights can modify these settings for now. Right now it seems to be showing new issues and comments and no changes. If it looks messier, we can create separate channel #collective which shows new proposals and comments.

We can create a Slack plugin to ask for active proposals for the week and maybe find a cleaner way to interact with GitHub to know which ones are breaking consensus. I will put forward a proposal by tomorrow for a smoother process with some automation and interaction.

[mbernst]

@shirishgoyal I look forward to that proposal!

There is a live proposal right now (#13) to make the Slack admin permissions more collectively determined. In the meantime, here is what we can do with the existing GitHub-Slack integration:

We can create a number of "configurations", each one tracks at one or more repositories. We can use checkboxes to syndicate any subset of the following events:
COMMIT EVENTS
Commits pushed to the repository
Only show commit summaries (no commit messages)
New comment on commit
ISSUE / PULL REQUEST EVENTS
Pull request opened or closed
Reviews on pull requests
Issues opened or closed
New comment on issue or pull request
Only show titles of new issues and pull requests
DEPLOY EVENTS
Show deployment statuses
OTHER EVENTS
Branch or tag created or deleted
Branch force-pushed

We can choose: which channel those events go into, what name the bot publishes as (e.g., "GitHub"), and an icon.

I share this so that we can articulate what is possible through the existing automation tools.

[neilthemathguy]

BREAKING CONSENSUS

@markwhiting said:

Yes, I created that folder to test it out based on this proposal. Before that I had created gists of those documents as part of this proposal. The gists are still on my account but I linked these ones because I thought it would be easier to have links that would not need to change.

I don't think you can have a repository without an owner. Explicitly, the aim of this would be to make it so that anyone in our community can completely use our governance mechanism. I'm happy to make that explicit in this proposal.

For > State of the proposal: active, approved, declined, voting
@mbernst said

I think Mark is currently wizard-of-oz'ing this. All proposals are currently active right now.

I think I'm raising a broader question here. I'm asking did we collectively decide who should take on this task? And how the person should execute it?

Sidelining the collective, while going ahead and executing these things is not the way of doing it. BREAKING CONSENSUS not for whether we need the documents or not, but for the way this has been done.

What concerns me the most is that people think they have some executive powers to do things.

[markwhiting]

@neilthemathguy, I see your point. It seems like perhaps this could be a separate proposal because your consensus break is not about the docs specifically but about who has access and who is running stuff.

I will clarify that the wizard-of-oz'ing aspect of this all, as in, what I am doing by hand, has just been setting up the templates etc., and inviting people to have write access. The only reason I'm doing this by hand is because we didn't yet have a system to manage everything, i.e. doing it automatically. I would very much like to move to a process that does not involve me doing any of these things by hand and just allows the system to run.

@shirishgoyal I like what you're suggesting. I think perhaps this proposal that you're mentioning would also support the changes that @neilthemathguy is thinking about.

[neilthemathguy]

Thanks! I just want to make sure that we are on the same page.

Could you tell what you comprehend from this line: No changes are made without a proposal, irrespective of how urgent or important it is .

[markwhiting]

Sure, this was written to mean we should not conduct actions before creating a relevant proposal to describe or give context to those actions. We discussed at length about if the proposal should require consensus to preempt action and landed on this wording to allow preparative action given a proposal, but not without one.

If I remember correctly this was argued to avoid wasting time, e.g. someone putting in a lot of work before seeking a proposal that might end up getting rejected, but also to avoid having to wait too long to start working on things, e.g. to allow people to start working on changes in code once they had submitted a proposal and were waiting for it to achieve consensus.

[qwertyone]

#23 This issue is an extension of the source control document.

[markwhiting]

Summary and intending to regain consensus

The concrete next step of this proposal is to separate out the operational aspects as we discussed in last week's meeting.

So, I have created a separate proposal #28 which outlines a few specifics of executing this governance, with regard to things like who has access to this repo and how it is managed.

While I think @shirishgoyal's comments are important, I think they might be more relevant to the operational proposal (#28)

Thanks, and please let me know if you think there are other specific elements of this proposal that should be modified.

---

Additionally, adding a few details to get this up to speed with the intended template.

Implications

The implications of this proposal are that we will:

1. have a public record of what we have agreed upon that is managed in a public and transparent manner as these documents evolve
2. have a formal way to modify these documents, e.g. proposal → pull request
3. have a structure for us to evolve these and other documents we use for governance

Contact

Mark Whiting is @markwhiting here and on slack.

[neilthemathguy]

Thanks! I really don't think we need to have CONTACT field in any of the comments or proposals. It makes things confusing. Can we stick to standard process.

[markwhiting]

Sure. I can add those above so that they are not out of place.

[neilthemathguy]

I mean we don't need a single person contact as many of this work of the Collective.

[markwhiting]

I agree. Perhaps we should update the governance documents to better reflect how to deal with proposals that are collectively proposed.

I think its strange listing the contact person like this, but I believe the governance documents say explicitly that we should.

[neilthemathguy]

Governance document doesn't say anything about adding the field called Contact.

It says Name and Slack username of the person or people who created the proposal

The proposals should reflect that.

[markwhiting]

We could list "The Collective" as the group who did it. I am totally open to another option as to how this should be done in this case.

[neilthemathguy]

Let's stick to the Governance Protocol for now--- Name and Slack username of the person or people who created the proposal. We need to remove CONTACT from all of the proposals.

Here people = anyone/group who worked on the topic in the past.

[markwhiting]

Updated to better reflect that. Still unsure how we do this ideally as listing names of individuals who helped author the documents seems disingenuous with attributing the collective.

[neilthemathguy]

I'm not sure what you are recommending here-- are you saying “written by the Collective”? or are you saying “written by [names of people]”?

[markwhiting]

"written by collective" in referring to the people who worked on the governance documents.

I think if we want to debate the authorship of the governance documents this proposal is not the appropriate place to do that. We could do something like add a header to one or all of the documents saying who worked on them, or whatever else, but that seems like its a separate proposal to edit the documents.

Of course, we also can't easily reach a point where we name everyone accurately because several of the documents were open to anonymous editors or suggesters during their writing.

[neilthemathguy]

moving here from #28

OK I’m not talking about authorship of the proposals. I’m trying to address a bigger issue that is reoccurring.

The current proposals, the way they are written, indicate that person who wrote them came up with those ideas/have done that work. Which is misleading. For instance, Constitution analysis #40--- aren’t many other people worked on this? Didn’t people collectively discuss this before? Were those people included in the making of this proposal?

[markwhiting]

moved here from #28 →

Well if it is read literally from the governance document, as in who helped write the proposal, then no, I wrote both of these myself. However, I think you are reading it to say anyone who has worked on related topics, and I don't know how we would do that. I mean in the case of the constitution analysis one, we have many options but no list would be complete without saying the entire collective participated in some capacity.

So, I really don't mind which path we choose at all. I was under the impression that the more literal interpretation was expected, but I'm absolutely happy to list the collective instead, or to not include this section at all and allow people to express their participation in some other way, e.g. through assignment, or thumbs up or something else.

What do you think?

[neilthemathguy]

Thanks for moving it here.

I would like to see inclusive ways in which people who have collectively worked on XYZ issues, will work together and write the strategy proposals. If a person writes the proposal about the Collective's past work, then proper attributions must be listed. I don't see that in many proposals.

[markwhiting]

Agreed. We should establish that kind of practice, and perhaps propose updates to our governance documents to be explicit about how this kind of attribution should be listed.

[mbernst]

@neilthemathguy I wonder if we can roll this into the revised proposal template #27? I see what you're saying. The contact section was derived from a combo of needing the proposal creator's slack ID, and a slack channel.

I was struggling with this in some of the proposals...can the author just name people who had substantial positive impact on the development of the proposal? We can't assign them as a way of giving credit, since the gov docs only allow self-assigning, but maybe a section like "Proposal Contributors" instead of "Contact"?

[neilthemathguy]

Added comment to the PR #26

For now to make sure attributions are clear, let's change Contact heading to Person or People Who Added the Proposal to GitHub

With a asterisk note below
**The person who added the proposal to GitHub--- the name in this section doesn't indicate that the person came up with this idea, unless and until explicitly and clearly mentioned.

and then names
XYZ

[markwhiting]

OK. I assume we will clean up that wording a bit, but I'll add that above for now.

[markwhiting]

Since the MD versions of the governance file are now out of sync with the google doc versions, I've prepared a PR around those updates which could be associated with this proposal. Here: #45

@neilthemathguy are there any other concrete changes you'd like to see to regain consensus on this?

[neilthemathguy]

I think this looks good. I think the documents should reflect people who were part of this process.

Let's add one section to the governance documents before we merge it:

• At the top of each document--- the authors who wrote the listed documents (Bernstein Michael @mbernst, Gaikwad Neil @neilthemathguy, Goyal Shirish @shirishgoyal, Whiting Mark @markwhiting)

• Below that--- names of people who commented (Gamage Dilrukshi @iceLearn, Gilbee Aaron @qwertyone, Richmond-Fuller Angela) If there are others in the doc add their names (last name, first name)

• Below that--- links to the Crowd Research Governance hangouts along with the names of participants ()

• Below that--- names of the people who participated in the voting

Further process about managing GitHub and other account is discussed in #28

[qwertyone]

Should we stop using google docs for governance and move all future efforts to github?

…

On 6 January 2018 at 20:21, Neil Gaikwad ***@***.***> wrote: I think this looks good. I think the documents should reflect people who were part of this process. Let's add one section to the governance documents before we merge it: At the top of each document--- the authors who wrote the listed documents (Bernstein Michael @mbernst <https://github.com/mbernst>, Gaikwad Neil @neilthemathguy <https://github.com/neilthemathguy>, Goyal Shirish @shirishgoyal <https://github.com/shirishgoyal>, Whiting Mark @markwhiting <https://github.com/markwhiting>) Below that--- names of people who commented (Gamage Dilrukshi @iceLearn <https://github.com/icelearn>, Gilbee Aaron @qwertyone <https://github.com/qwertyone>, Richmond-Fuller Angela) If there are others in the doc add their names (last name, first name) Below that--- links to the Crowd Research Governance hangouts along with the names of participants () Below that--- names of the people who participated in the voting — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFy3xrqCNz1p7Q7Klgf32R2rMG7r3iwrks5tH8efgaJpZM4RADUm> .