dsholler
commented
5 years ago For any form of organized activity, it is likely more constructive and efficient to teach and reward desired behaviors than to change problematic behaviors down the line. Project decision-makers can prompt desired practices in open source software development by providing newcomers with “how to contribute” guidelines in easy-to-find, readily-available places. Many projects follow GitHub’s recommendation for placing such information in a CONTRIBUTING.md file [1]. Other projects, such as the Apache Open Office Suite [2] and rOpenSci [3], provide text-based newcomer manuals and learning modules accessed through a web interface. Still others take a more interactive approach, such as the GNOME project’s Newcomers Guide, which walks potential contributors through the contribution pipeline: choosing a project, acquiring and installing the necessary computing tools, finding problems or choosing issues to work on, submitting changes, and following up on feedback [4].
“How to contribute” guidelines,” no matter the form of presentation, serve several additional purposes alongside describing expected contribution behaviors. Contribution guidelines offer a centralized, well-organized description of resources a newcomer can consult while learning to navigate the project’s technical and social environments [5]. Indeed, the social environment is a key constraint on newcomer behaviors [6]; explicitly-stated definitions of contribution expectations can ease newcomers’ hesitancies about whether or not their work is sufficient and suitable for the project. Relatedly, guidelines also acclimate newcomers to the norms of work and communication, particularly when items such as necessary computing tools and codes of conduct are foregrounded. In sum, when combined with a welcoming, inclusive environment, clear expectations about legitimate participation, and shared software development goals, contribution guidelines can help newcomers feel they are on equal footing with veteran project members.
Project decision-makers should keep in mind, though, that their perceptions of what constitutes clear, easy-to-find contribution guidelines may not align with the perceptions of the newcomers themselves. Continual reevaluation of the guidelines based on community member feedback is essential to ensuring that contribution guidelines are achieving desired effects and do not fall out of date (e.g., as technical and social elements of the community change). In this sense, contribution guidelines should be treated as living, evolving documents rather than immutable rules.
[1] https://help.github.com/articles/setting-guidelines-for-repository-contributors/ [2] https://openoffice.apache.org/orientation/intro-contributing.html [3] https://ropensci.github.io/dev_guide/, Chapter 14: Contributing Guide [4] https://wiki.gnome.org/Newcomers/SubmitContribution [5] Zanatta, A. L., Steinmacher, I., Machado, L. S., de Souza, C. R., & Prikladnicki, R. (2017). Barriers faced by newcomers to software-crowdsourcing projects. IEEE Software, 34(2), 37-43. [6] Steinmacher, I., Conte, T., Gerosa, M. A., & Redmiles, D. (2015, February). Social barriers faced by newcomers placing their first contribution in open source software projects. In Proceedings of the 18th ACM conference on Computer supported cooperative work & social computing (pp. 1379-1392). ACM.
gvwilson
Borrowed from my IEEE Software paper:
"we suggest to give newcomers all the resources they need (and only those). It is important to show what is essential for their first steps, how the project is organized, and what/where the important resources are (e.g., code repository, mailing lists, issue tracker, IRC channel, code review tools). This information should be well-organized and easy to follow. Some projects (e.g., Gnome projects and Open Office) offer a “how to contribute” or “introduction to development” page. Complementarily, GitHub encourages maintainers to have this kind of information in a CONTRIBUTING.md file, including general information about ways to contribute, paths to obtaining the current codebase, mailing list addresses and etiquette code, introductions to issue tracker systems, build guidelines, etc. "
In addition, it is important to keep it up-to-date, or identify outdated information, which can be misleading to a newcomer seeking for a reliable source of information