Back in the day, before open source won the Closed vs. Open Wars (especially in scientific computing),
RTFM.
was a common first response when a new developer sought to contribute to an open source project. RTFM stands for Read the Fine Manual, although there is also another, more crass, interpretation.
We can do better!
And in modern times, we must do better as a pragmatic imperative. In our overloaded, hectic lives, few have the time to read every project's manual before they submit a small fix. Moreover, as a new generation of developers are impatient with interactions beyond swiping a screen, they are not going to proactively sign up for a GNU Mailman mailing list, seek out and read all associated manuals, search mailing list archives, and then post to the list according to the conventions of the community. While forking and maintaining patches should be avoided when possible in the interest of long-term maintainability, modern tooling for version control and testing makes it slightly more feasible. In general, a potential contributor's time, attention, and energy are in short supply, and we need to make their introduction to the contribution process as painless as possible.
At the same time, as community-driven maintainers of open source projects, we must limit our time, which is in even shorter supply, while upholding the project's culture, quality, and sustainability.
In this post, we review how the Insight Toolkit (ITK) leverages the first-interaction GitHub Action to communicate our appreciation of the efforts of first-time contributors, establish norms for behavior, and provide civil pointers on where to find more information.
Example first interaction welcome message
Automated outreach on first interaction
While GitHub has made many improvements that facilitate social coding, including resources to automate pointers to contributing guidelines that are put forward and easily discoverable using relative links and a project's code of conduct for new contributors, configuration of the first-interaction GitHub Action is another mechanism that can be customized to a project's needs.
The first-interaction GitHub Action adds a comment whenever a first-time contributor opens their first issue or pull request. This automated message connects with contributors where their attention is already directed.
A note of welcome and appreciation
Our comment starts with a note of welcome to the community and gratitude for the effort made to contribute back to the project. Software development, regardless of the cold and mechanical nature of computers, is a social endeavor; we respect and acknowledge this by beginning with our gratitude.
Recently, emojis were added to the message to communicate a welcoming culture. 🤗
Communicate mission, values, and culture
Next, we provide a link to our community participation guidelines / Code of Conduct. This establishes culture and communicates behavioral expectations, along with the project's mission:
ITK is one of the largest and long-lived open-source projects within the scientific community. ITK is made by hundreds of community members around the globe with a diverse set of skills, personalities, and experiences working for open and reproducible research in image analysis.
We work to build a great image analysis tool that serves a broad range of applications and environments, from research and education, to industry and beyond, by trying to contribute with amazing features, and teaching and helping our fellows for such a honorable intention. We seek no explicit recognition for this. Hence a sense of additional responsibility is part of why we do what we do.
We want a successful, friendly, agile and growing community that can welcome new ideas in a complex field, continuously improve our community software process, and foster collaboration between groups with very different needs, interests and skills. Openness, collaboration and participation are core aspects of our work - from development of new amazing image analysis features, to collaboratively shaping the necessary tools to make it an ever easier and joyful experience for both developers and end-users. Such an environment enriches the surrounding community and other open communities as well.
We put people first and do our best to recognize, appreciate and respect the diversity of our global contributors. The ITK project welcomes contributions from everyone who shares our goals and strives to contribute in a healthy and constructive manner within our community. This implies diversity of ideas and perspectives on often complex problems. We gain strength from diversity and actively seek participation from those who enhance it.
And our values:
- be open
- be welcoming
- be inclusive
- be civil and considerate
- be respectful
- be collaborative
- be careful in the words that we choose
- take responsibility for our words and our actions
- be concise
- be inquisitive
- moderate your expectations
- ask for help when unsure
- lead by example
Share where to find more information
Finally, we provide guidance on where to find more information for contributors with issues or those that would like to integrate a patch. For issues, we point contributors to prior issues and the discussion forum. For pull requests, we point to documentation on our contribution process.
Conclusion
Configuration of a first-interaction GitHub Action is a relatively small step, but it has large impact in the greater battle to achieve software sustainability.
We will continue our aim to move beyond RTFM to WYBC (Welcome Your Brilliant Contributors), CMVC (Communicate Mission, Values, and Culture), SYCD (Share Your Contributor Documentation), and CUBA (Come Up with Better Acronyms) 😊.
Top comments (1)
Great