[RFC] Governance Models and Methodologies for Package Maintainers

[thescientist13]

Overview

Coming out of the recent WG meeting (#305), one of the topics that came up while discussing the Express project was an issue started by @wesleytodd to help establish repo owners for the project, who could help maintain the code base and its packages, and share in the responsibilities as it relates to help with triage / review / and general code ownership.

It was reasoned that having something like this, even in a generic fashion, or like picking a OSS license for the model that best suits your needs, can help package maintainers deal with the influx of attention popular packages can attract and as such, can help with not only ensuring successful technical maintenance / growth of the project itself, but also alleviate the burden on the maintainer(s).

That said, this is not intended to be a one size fits all endeavor per se, and so casting a wide net certainly helps us cover as many use cases as possible, even if maintainers just end up cherry-picking from the content that gets derived as the result of this work here. At least being able to provide a resource / reference / starting point could be a very valuable tool in a toolkit for package maintainers.

Proposal (TBD)

While there are probably some generally useful recommendations that can be applied by all / most packages, ultimately authors would be encouraged to best adopt a model / policy that best supports their particular package if no one particular size fits.

Some examples of recommendations that could come out of an effort like this are:

1. Create a contributing.md, if you don't already have it to document the model you want (good first step in general for articulating the vision of how you would like your project to operate, to better guide further technical / operational decisions)
2. Use GitHub's Code Owner's feature
3. Take advantage of project / Issue planning (i.e. using Project's and Milestone's to guide visibility into priorities / roadmap). Also good to have documented in the README
4. Take advantage of GitHub bots / CI to help with code review and issue triaging
5. Using branch protections / teams to administer repos, auto assign PRs, etc

From a per project perspective, and given size, actually advancing / promoting contributors (if at all) would have another related of policies as well. How would one measure the contributions of a contributor? (an interesting point covered in the Express PR I linked to). Time? commits? comments? All of the above? These sorts of decisions could vary greatly from project to project, but if any consistent themes emerge, certainly we can try and provide some general purpose guidelines.

Either way, understanding that the technical side and interpersonal side of things may (and should?) be handled differently and so accounting for those distinctions may be helpful from the outset.

---

Next Steps / Feedback

I think a good next step would be to review some of the high impact projects in the community (in the OpenJS Foundation) to see if there are some good resources / examples already in place that we can start from. Projects like:

• webpack
• Express
• NodeJS
• others (jquery, mocha, ESLint)

Hearing / seeing from the community and what they've tried and found success with (or lack thereof) will allow us to not have to start in a vacuum. Some questions / metrics to consider as this happens could be:

• Size of the project (LOC / packages / repos?)
• Avg. commits / PR (per month?)
• What are you using now, if anything, for your project?
• Is the project using any sort of CI / automation for PRs / issue triaging
• Is there something that you wish you had from the community (tooling, methodologies, docs, etc)
• Are there any SLAs already in place?

Would also be a good to follow along and absorb any relevant feedback from these package / project engagement efforts:

• [key packages] Pilot Packages #142
• [key packages] High Impact Packages #143
• [key packages] Open Enrollment #144

Feedback welcome! This is very much a starting point to get our ideas captured and written down and be used to build off of.

[ljharb]

(Netlify requires compulsory advertising/shilling in exchange for their “free” open source project plan; let’s avoid endorsing specific companies given that we have no influence over problematic policies)

[thescientist13]

Fair point in regards to endorsing other companies. I've seen similar discussions around other repos to that effect and makes sense to me. Updated.

[wooorm]

Hi! 👋 Sorry to barge in but I like thinking about governance, and did so a while back for the unified collective on unifiedjs/collective. This could be interesting to y’all as another source of inspiration maybe?

(p.s. unified is hundreds of infrequently updated modular packages spread out over several organizations, in total getting about 3B downloads a year from npm, maintained by a loose group of people that are typically only interested in a small part of the collective, with an okay opencollective income)

[thescientist13]

Took some time to review the existing docs, surveys, and issues in this repo and was able to draw a lot from that well of resources. I was thinking that maybe a Governance doc could be authored / presented as a single entry point for package maintainers to all existing content? It could present a single cohesive overarching narrative in its tone / authoring, while also acting like a table of contents / guide for readers.

Where there exists something in docs/, the text can link and reference that material and so the reader can choose to go more in depth on that topic if they like.

In general, having a single entry could be really helpful for quickly sharing and gathering all our (e.g. WG participants) collective thoughts into one place and organizing everything to make it easily discoverable / searchable when shared by readers.

I started putting together a Table of Contents to guide this document and gather feedback around it. (in no particular order)

Table of Contents

1. Intro / Goals
   • provide consistency and predictability in expectations for maintainer's and contributors
   • help to add process and organization
   • reduce overhead of common ceremonies through automation
   • bring on, and engage with, contributors in an ongoing way
   • security and dependability to the health of your package
2. Assumptions
   • GitHub
3. Repository Settings
   • Branch Permissions
   • Manage Access
   • Licensing
   • Badges?
4. Workflow
   • Contributing.md
   • Roadmap (pointing people in the right direction)
   • Projects / Milestones / Labels (good first issue, pinned issues)
   • Templates
   • Automation (CI)
     • linting
     • testing
     • build matrix
     • ci-cd-guidelines
   • Code Owners
5. Code of Conduct
6. Security
   • 2FA
   • Dependabot / Greenkeeper
   • Lock files
7. Release Management
   • Publishing
   • CITGM
8. Support

---

Or, playing my own devil's advocate, maybe this scope is too broad? Maybe governance as a topic should be condensed to something smaller (to what degree / boundaries?) and an actual index.md should be created as a literal table of contents instead (and nothing more)?

---

Anyway, eager to contribute content for all the above topics, either improving / organizing existing docs, or authoring those not already drafted. More or less wanted to present my thoughts and progress for feedback and guidance before diving into the deep end on all this.

Was also thinking, could we share the survey with other projects, even without the intent to pilot them? I found the surveys as good reference material and thought more of that could be helpful, even if for our own internal organization and planning / designing.

[mhdawson]

Tagging so we discuss at the next meeting.