Governance of maintained projects

[danielcompton]

@hlship raises some good questions about how to vizdeps should be managed, and also more generally how CLJ Commons projects should be managed: clj-commons/vizdeps#5.

• What is the PR review protocol? For example, is one review enough, or should changes be reviewed by two committers?
• Is there a CLA?
• Who determines when to perform a release?
• Who is responsible for the actual release?
• Where do we make post-release announcements?

I also raised some questions here on the governance of adopted projects: https://clojureverse.org/t/clj-commons-first-project-resurrecting-unmaintained-projects/3164

• Do we want to set some entry requirements for people that are willing to be responsible for maintenance?
• Should we set some exit criteria for projects that we adopt but then become superceded or no longer used? Where do those projects go?
• I think it would be quite useful to have some number of people (more than one?) who commit to maintaining this new project under the clj-commons banner. We don’t want the new home of the project to become unmaintained as well.
• What are the minimum requirements for maintenance of a project? Some ideas:
  • Passing continuous integration
  • Responsive to issues and pull requests
  • Documentation
  • Regularly creating releases
  • Staying up to date with new Clojure and JVM releases

[danielcompton]

• Is there a CLA?

I'm not sure what a CLA would buy us here? We would retain the ability to relicense the codebase (perhaps to EPL 2.0 + GPL compat), but if we're adopting an existing project that doesn't have a CLA then we would still need to get copyright assignment from all previous contributors too.

There are some good arguments against CLA's here: https://www.joyent.com/blog/broadening-node-js-contributions. I haven't studied it much, and I'm not strongly against them, but they do add friction, so we should be getting something that is worth the cost of that friction.

The last question is, who would the copyright be assigned to? CLJ Commons isn't a legal organisation, just a loose collection of individuals working on projects together. I'd like to make it easy for people to come and go as life changes for them, so having people owning the copyright seems a little tricky.

What is the PR review protocol? For example, is one review enough, or should changes be reviewed by two committers?

I think I'd be happy to let the maintainers of the projects decide that amongst themselves, perhaps with the general recommendation that ideally at least one other person reviews and approves a PR. For tricky or dangerous changes then it would be good if more people were able to review it.

Who determines when to perform a release?

Not really sure, but I'd err towards more frequent releases rather than less frequent. I think it would probably be a conversation amongst the maintainers of the project.

On that point, I think it could be a good convention to have a CODEOWNERS file which lists who is a maintainer of a particular project, e.g. https://github.com/clj-commons/ring-buffer/blob/master/.github/CODEOWNERS.

Who is responsible for the actual release?

It would be nice if we could set this up to be done in an automated manner in CI, perhaps triggered off a git tag? Then any maintainer could run lein release (with a modified set of :release-tasks) and after pushing the release, CI would deploy to Clojars. clojars/clojars-web#709 is a bit of a blocker on this though, and on delegating releases in general.

Where do we make post-release announcements?

For releases that people are likely to be interested in hearing about then probably Clojure mailing list + Clojurians Slack? We don't want to over spam people though.

[cnuernber]

My recommendation is to have one person solely responsible for any given project. They can delegate however they like but at the end they are responsible for maintaining the project and for finding a new maintainer should they start to get tire of the responsibility. Err on the side of more relaxed in the beginning I think as this will provide early growth.

Aside from that there can be some level of meta people, maybe just 2 or 3 who have access to everything. This is still a very small endeavor so it isn't necessary to think out too many things yet.

Who is responsible for the actual release?

If CI is responsible, then I think that the clojars bug is not so pressing. My vote is to work to get CI involved in every one of these projects and have some special CI command that states 'not only test but release this to clojars under this version if the tests pass'. Something simple.

My opinion is that anything aside from small, simple, lean is not worth it.

So here is my vote on the above questions, starting with the PR questions

• PR review protocol - up to maintainer, defaults to 1 approval. Should be clearly stated on the PR template.
• No CLA. I understand the arguments but I haven't seen them effective in practice aside from turning potential contributors away. Given this community is already very small I think that is a bad move.
• Release determination - up to maintainer.
• Release responsibility - Ideally we can give a command to CI to do it. This then boils down to who has the rights in CI for releases in this project which is something we may be able to solve via github.
• Post release announcements - Good question. I think I will defer to other people as that is not a specialty of mine.

Now to the more general questions from clojureverse:

• Entry requirements - maybe a couple PR's to the project or some substantial history of opensource work?
• Exit criteria - This is a great thing; something that is superceded means the community learned a bit and found a better path which we should all be very happy for. I would just clearly state this project is superceded on the readme and link to the new project.
• More than one will be hard to swing at first. Ideally the clj-commons organization has sufficient depth itself but any given project may not. Two or more people means there is always at least some question of who pulls the levers.
• A minimum contract for the one maintainer who volunteered to help the project is wise assuming it is very very little work from them. Those bullet points are sound but I would be very careful enforcing anything like that unless you have lots of people knocking on the door. I think once the project is in the organization we can handle whatever happens without too much trouble.

This really gets into opensource organization management. I am thinking perhaps just a couple things:

1. Branding - clj-commons.org - an image or two that is clear and memorable, plus a bit more depth. The kernel there is good but also a list of people, some contacts, etc. Is there a github project for the clj-commons.org site that we can contribute to?

2. We figure out common CI sooner rather than later. Once that is done we can integrate projects into it one by one and at least know things aren't getting worse and it may clarify question around releases have a release system in place.

Lots to figure out for something new :-).

[hlship]

I'm fine without a CLA, but I think it's important that we ensure that PRs assign copyright to ... someone.

I generally do my releases manually; I hand edit project.clj, do the tags and push, then the release to clojars. I don't see that as a big obstacle; it would be cool if we could get a CI to do it automatically when there was a new version, but that's a scaling issue that we don't really have.

CircleCI has been great for CI work, and free for open source. I'm already using them for things like Lacinia and such.

I'm really, truly, awful, and anything bureaucratic BUT having a open, transparent process is intuitively a good idea.
From working on Apache projects, I'm used to the idea of voting on important things (but chafe at the idea of slowing down for votes).

I can imagine a simple process whereby one or more committers are "senior" and have the authority to plan and perform releases with a small amount of notice.

I would also say that adding new committers to a specific should be based on a vote among the current committers; not sure of the scope, whether it should be comitters of the specific project, or across all clj-commons projects.

In terms of a process, the goal should be that these projects should not feel "abandoned" again, now that they've been re-homed.

[bbatsov]

I'm fine without a CLA, but I think it's important that we ensure that PRs assign copyright to ... someone.

Why so? Unless you plan to re-license a project that's pointless. And because the existing code probably didn't do this assigning the copyright to someone won't get us far.

The only reason why Clojure has its special licensing is so that they can relicense it whenever they feel like it, which probably makes sense for a project of that magnitude, but probably doesn't make sense for small libraries.

[seancorfield]

With what's on clj-commons.org now and the seeming consensus here, it feels like all the original questions got answered?

• What is the PR review protocol? For example, is one review enough, or should changes be reviewed by two committers? -- up to the maintainer of each project
• Is there a CLA? -- no
• Who determines when to perform a release? -- the maintainer of each project
• Who is responsible for the actual release? -- the maintainer of each project
• Where do we make post-release announcements? -- main clojure Google Group and Slack if important enough -- up to the maintainer
• Do we want to set some entry requirements for people that are willing to be responsible for maintenance? -- done: posted to clj-commons.org
• Should we set some exit criteria for projects that we adopt but then become superceded or no longer used? Where do those projects go? -- beyond the scope of clj-commons -- deal with it on a case-by-case basis
• I think it would be quite useful to have some number of people (more than one?) who commit to maintaining this new project under the clj-commons banner. We don’t want the new home of the project to become unmaintained as well. -- CODEOWNERS
• What are the minimum requirements for maintenance of a project? -- done: posted to clj-commons.org

Does anyone here still think any of these are open issues that need further discussion?

Does the clj-commons.org website need any further updates to clarify this consensus?

[bbatsov]

Do we want to set some entry requirements for people that are willing to be responsible for maintenance? -- done: posted to clj-commons.org

Where exactly? I don't see any updates on the site.

What are the minimum requirements for maintenance of a project? -- done: posted to clj-commons.org

Same here - I can't find anything on the subject.

Does the clj-commons.org website need any further updates to clarify this consensus?

I agree with everything you said in general, but I do think some practical questions need to be addressed as well:

• are we pushing for/avoiding changing artefact coordinates?
• forking over moving?
• do we (try to) set any common standards for the coding style of projects, their CI, etc or it's every project for itself.
• what's the role of the clj-commons leadership?
• common funding for clj-commons?

Obviously those are nuanced topics and I doubt we'll just have a blanked solution for them, but some coverage would be beneficial IMO.
Generally it seems to me a nice FAQ might be useful on the landing page. Might also be a good idea to clarify where clj-commons stands compared to Clojure Contrib and maybe mention other similar project "holdings".

[seancorfield]

Doh! They're posted to the readme of this meta repository -- my bad. That should either be promoted to a page on the site or the home page should link to it. It answers some (but not all) of the other questions you post too.

[seancorfield]

Entry criteria: https://github.com/clj-commons/meta/blob/master/README.md#entry-criteria

Maintenance criteria: https://github.com/clj-commons/meta/blob/master/README.md#maintenance-criteria

Transfer vs fork/artefacts: https://github.com/clj-commons/meta/blob/master/README.md#when-to-use-the-clj-commons-maven-group-id-vs-the-original-group-id (also covered in @slipset 's proposed #49 )

Common coding style: I'd rather leave this up to each project maintainer rather than try to impose a "house style" since the projects coming in may already follow different styles.

Leadership: hands-off as far as projects are concerned, light touch on the organization. This is about trying to ensure important/popular projects have a home and a maintainer so they can be sustained. The leadership is mostly administrative at this point. As the long term goals start to solidify into actions, there may well be more hands-on work needed.

Funding: clj-commons isn't an organization so it can't accept funding on behalf of projects. I think Clojurists Together covers that separately.

[seancorfield]

Project Governance: https://github.com/clj-commons/meta/blob/master/PROJECT_GOVERNANCE.md

Between the readme and the new project governance page, are there still issues left unaddressed that you think are important to be addressed? If not, we can close out this issue (and potentially start new issues for additional discussion points).

[seancorfield]

(I updated clj-commons.org to link to both of those, under Contributing)

[bbatsov]

Thanks!

I think it might be best to fold all the documentation in a single README and just publish it to clj-commons.org via some CI job. This works really well with AsciiDoc - it's how I publish https://guide.clojure.style

[seancorfield]

The plan is to convert clj-commons.org to use Hugo and then it will have several pages and the information can all be migrated out of this repo's .md files into real pages on the main web site.

[MalloZup]

I think we could from this big card, create smaller issue and reference them to this kind of epic card.

[seancorfield]

A few aspects of this issue have come back up again and I think some editorial work on the clj-commons.org home page and the meta repo could address the concerns. I'll take a look at it over the next few weeks.

[seancorfield]

Information about accepting and maintaining projects has now been distilled into two new pages on the main website:

• https://clj-commons.org/accepting-projects.html
• https://clj-commons.org/maintaining-projects.html

I have added ORIGINATOR and CODEOWNERS to all the current projects where they were missing, and regenerated the projects page.

I've also added the logo as a "home" button to all four pages there to make navigation a bit easier.

I've reviewed all of the issues raised here and I believe all of them are covered by those new pages, except for what should happen with a clj-commons-maintained project that needs to exit or sunset. I believe we can decide what to do about that if and when it happens, on a case-by-case basis.

Thank you, everyone, for your input! If you think there are still issues that need clarifying/addressing, feel free to open new issues here in meta and we can continue to discuss them and expand the website as needed.