[Proposal] Revamp our Community docs to clarify governance and contributor pathways (meta-issue)

[niksirbi]

Background

I have been participating in the Birdaro training program on behalf of movement, as part of their pilot cohort. Birdaro is an initiative—managed by the Center for Scientific Collaboration and Community Engagement—that supports people in leadership roles within open-source projects as they navigate growth, scaling, and sustainability.

Currently, I’m taking part in their multi-week course Creating documentation to support participation and collaboration (a.k.a. Creating Community Playbooks). As part of that course, I conducted an audit of our current “Community Playbook,” which lives in the Community section of our website, and developed a use case for improving it.

Use case for a better “Community Playbook”

The movement project is an open-source Python package that has been in active development for about two and a half years. It is led and maintained by four core developers (including myself), all members of the same research software engineering team. While the maintainers handle most day-to-day development, the project openly welcomes contributions from anyone, and now has around 30 volunteer contributors with diverse backgrounds and motivations.

This growth has been supported by our existing community documentation, which is publicly available in the Community section of our website. It includes our mission and scope, design principles, contributor lists, communication channels, a development roadmap, and a detailed contributing guide.

However, this current “playbook” needs to evolve to match the community’s growth and the increasing complexity that comes with scale. At present, the contributing guide mixes information intended for both maintainers and external contributors (see issue #664) and focuses mainly on code contributions. It offers limited guidance for newcomers interested in simpler or non-code contributions and lacks sufficient detail on testing—an area where contributors often need more support.

In addition, the project currently lacks a clear description of its governance structure. While we already follow some implicit norms around decision-making and responsibility, these need to be made explicit, especially given that all maintainers are employed by the same host institute. We also want to define a clear pathway for community contributors to become maintainers, recognising their efforts and strengthening long-term sustainability. Formalising these processes in a playbook will clarify roles, make expectations transparent, and support a more inclusive and scalable collaboration model.

My key takeaway

A key challenge for movement as it scales is the separation between core maintainers and the wider community. We are fortunate to attract motivated contributors who care about open science and technical excellence, but participation could be made more accessible, structured, and rewarding.

We already work to reduce the information gap by keeping most communication public on GitHub, Zulip, and our website. However, since all core maintainers are co-located, many discussions still happen informally and aren’t always shared externally. Maintaining transparency therefore depends on our discipline to document and publish such conversations and make our processes explicit.

Ultimately, the best way to blur the lines between the core team and external contributors is to provide a pathway for reliable contributors to gradually take on more responsibility, gain decision-making power, and eventually become maintainers. This will greatly improve long-term sustainability: if paid maintenance ever becomes infeasible, a well-structured community could take over stewardship.

Content that could be added

These are the areas identified during my audit, open for feedback and discussion. Implementing them will likely take multiple pull requests, led by myself and other members of the core team.

Note

Consider this a meta-issue.
Over the next weeks I’ll break down these tasks into smaller, more focused issues.

Maintainer guide

We need dedicated how-to guides for core team members (maintainers), separate from the contributing guide aimed at community contributors.

Possible topics include:

• Triaging issues
• Reviewing pull requests
• Organising community calls
• Making releases (we already have a draft internally; this should be made public)

Expanded and restructured contributing guide

Should include:

• How contributing benefits both the project and the contributor (could also appear on the Mission & Scope page)
• What contributors can expect from us (review process, feedback, recognition)
• Different forms of non-code contributions and how to make them
• More guidance on testing and writing tests

Beyond adding content, the guide should be restructured to help users quickly find what they need—e.g. reporting a bug, asking a usage question, improving docs, or promoting movement in their lab. Inspiration for this can be drawn from the playbooks listed below.

Governance

A governance page describing roles and decision-making processes, including:

• Defined roles and stakeholders: who is who, and the responsibilities of maintainers
• How to become (or step down as) a maintainer
• How major changes are proposed and decided
• How credit, recognition, and authorship are handled

For reference, see the slides I recently presented on movement’s emerging governance.

Materials & Outputs

A public record of project materials—logos, posters, slides, recorded talks, figures, etc.—would help contributors promote the project and represent it in their own networks.

Miscellaneous improvements

• Link the Code of Conduct from relevant doc pages
• Update our Roadmaps and link to the GitHub project board
• Expand the Related projects page to better situate movement within the wider ecosystem, see existing issue Expand on "Related Packages" in the README. #58.

Inspiration

Below are examples of well-crafted community playbooks and related reading materials.

Good playbooks

• https://compass.2i2c.org/
• https://contributing.ropensci.org/
• https://www.pyopensci.org/handbook/
• https://napari.org/dev/community/index.html
• https://github.com/Parsl
• https://openrefine.org/community
• https://www.astropy.org/contribute.html
• https://docs.jupyter.org/en/latest/contributing/content-contributor.html
• https://openmrs.org/get-involved/
• https://learn.scientific-python.org/contributors/

Further reading

• Ten simple rules for helping newcomers become contributors to open projects
• Open Source Guide on Leadership and Governance
• Governance of Open Source Software
• An Introduction to Governance
• Governance for Software Engineers
• GitHub’s Minimum Viable Governance (MVG)
• governance.md

I’d love to hear your thoughts!

To @neuroinformatics-unit/behaviour and anyone else who is interested in movement:

Please use this issue to share feedback, suggestions, or examples from other projects that we could learn from. The goal is to shape these ideas together.