Shared governance and contrib docs

Development
1

From @yanokwa:

We have a lot of repos that basically have the same CONTRIBUTING.md file. It'd be awesome if we could standardize on that in some way. Ditto with LICENSE, SUPPORT, CODE_OF_CONDUCT. They are kind of docs, but kinda governance.

And some never change (code of conduct), but others change sometimes (contributing).

And some are basically the same, but with minor tweaks for different tools.

It would be good to figure out what can be pulled out into a single source, and what needs to stay disaggregated. And, of the single-source/shared stuff: where does it live and who "owns"/manages it.

Is it docs? Is it a new repo of shared resources?

This is a discussion. Especially helpful would be examples of how other large multi-product/multi-repo projects do this stuff.

1 Like
2

My personal opinions on this subjective topic, based on generalized best practices I've seen elsewhere:

  1. Your license is the most important item and should be included in full in each software repository. Best practice here can come from the ASF: For less duplication, you can use APL license headers in community-produced source code files, but not in 3rd party dependencies. Remember, copyright statements by contributors should go somewhere else, like a NOTICE file.

  2. The canonical community Code of Conduct should live in some type of community-wide repo, e.g., https://github.com/opendatakit/governance. You could keep pointer files in each repository for good practice, but just a header-style notice pointing people to the canonical version.

  3. I would fork & tweak each CONTRIBUTING file to be focused on that repo. Yes, there will be some duplication. Maybe the upstream could also live in the governance repo, and people could start from there when they created new repos.

1 Like
3

Pointer files

Is this an actual magical git thing, or do you just mean regular files that reference the main repo?

I normally hate submodules, but would this be an appropriate place to have canonical docs sit in a standalone repo that is then submodule-ref'd in all the others?

4

I would like to second this statement.
And I know other repos don't have this same problem, but: I don't like the idea of having to explain submodules to non-coding doc contributors who are barely getting their head around git.

5

I'm a little confused about the pointer file comments. My understanding is just having something to point to the Code of Conduct and other documents like that. I think it makes sense to not spread them out over multiple repos so we can update in one place.

1 Like
6

Here's a example I just wrote -- public domain, feel free to improve upon it, or discard it!

CODE_OF_CONDUCT.md

By participating in, or contributing to, the Open Data Kit community and our collective works, you agree to be bound by the Open Data Kit Code of Conduct, published at: https://opendatakit.org/participate/

Questions about our Code of Conduct can be addressed to the ODK Project Management Committee at pmc@example.org.