Lack of clear guidance affects the growth of the project's community and may result in missed opportunities for valuable contributions.
A contribution policy on GitHub outlines the rules and guidelines for contributing to a project.
This policy helps ensure that contributions are consistent, high-quality, and align with the project's goals and standards.
It typically covers aspects such as the process for submitting contributions, coding standards, testing requirements, and how to communicate with the project maintainers.
There is a need to provide clear and concise guidance to potential contributors, outlining the various ways they can contribute and the steps they need to follow to ensure their contributions are successful.
Decision Drivers
Clarity: The contributing.md file should provide clear and concise instructions on how individuals can contribute to the project. Clear communication ensures that contributors understand the process and can engage effectively.
Accessibility: It's important to make the contributing.md file easily accessible to potential contributors. This involves placing it prominently in the project repository and ensuring it's easy to understand for individuals with varying levels of technical expertise.
Inclusivity: The contributing.md file should welcome contributions from individuals of diverse backgrounds and skill levels. It should avoid using exclusive language or assumptions about contributors' knowledge.
Guidance: The file should provide comprehensive guidance on various ways to contribute to the project, including reporting bugs, suggesting enhancements, and submitting pull requests. It should also outline any specific requirements or expectations for contributions.
Alignment: The contributing.md file should align with the goals and objectives of the project. It should encourage contributions that support the project's mission and vision while providing flexibility for innovative ideas and suggestions.
Compliance: Ensure that the contributing.md file complies with any relevant project policies, such as a code of conduct or licensing requirements. It should also adhere to any established contribution workflows or standards within the project's community.
Feedback Mechanism: Consider incorporating a feedback mechanism in the contributing.md file, such as a contact email or link to the issue tracker, to allow contributors to ask questions or seek clarification on the contribution process.
Regular Updates: Regularly review and update the contributing.md file to reflect changes in the project's contribution guidelines, workflows, or community dynamics. Keeping the document up-to-date ensures that contributors have the most accurate information available.
Considered Options
[option 1]
[description | example | … ]
Good, because [argument a]
Good, because [argument b]
Bad, because [argument c]
Decision Outcome
Chosen option: "[option 1]" Reason(s): [e.g., only option which meets criterion | comes out best (see below)].
Positive Consequences
[e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
Writing a good Contribution Policy
Context and Problem Statement
Lack of clear guidance affects the growth of the project's community and may result in missed opportunities for valuable contributions.
A contribution policy on GitHub outlines the rules and guidelines for contributing to a project.
This policy helps ensure that contributions are consistent, high-quality, and align with the project's goals and standards.
It typically covers aspects such as the process for submitting contributions, coding standards, testing requirements, and how to communicate with the project maintainers.
Github file name convention:
CONTRIBUTING.md
Example: https://github.com/jessesquires/.github/blob/main/CONTRIBUTING.md
There is a need to provide clear and concise guidance to potential contributors, outlining the various ways they can contribute and the steps they need to follow to ensure their contributions are successful.
Decision Drivers
Clarity: The contributing.md file should provide clear and concise instructions on how individuals can contribute to the project. Clear communication ensures that contributors understand the process and can engage effectively.
Accessibility: It's important to make the contributing.md file easily accessible to potential contributors. This involves placing it prominently in the project repository and ensuring it's easy to understand for individuals with varying levels of technical expertise.
Inclusivity: The contributing.md file should welcome contributions from individuals of diverse backgrounds and skill levels. It should avoid using exclusive language or assumptions about contributors' knowledge.
Guidance: The file should provide comprehensive guidance on various ways to contribute to the project, including reporting bugs, suggesting enhancements, and submitting pull requests. It should also outline any specific requirements or expectations for contributions.
Alignment: The contributing.md file should align with the goals and objectives of the project. It should encourage contributions that support the project's mission and vision while providing flexibility for innovative ideas and suggestions.
Compliance: Ensure that the contributing.md file complies with any relevant project policies, such as a code of conduct or licensing requirements. It should also adhere to any established contribution workflows or standards within the project's community.
Feedback Mechanism: Consider incorporating a feedback mechanism in the contributing.md file, such as a contact email or link to the issue tracker, to allow contributors to ask questions or seek clarification on the contribution process.
Regular Updates: Regularly review and update the contributing.md file to reflect changes in the project's contribution guidelines, workflows, or community dynamics. Keeping the document up-to-date ensures that contributors have the most accurate information available.
Considered Options
[option 1]
[description | example | … ]
Decision Outcome
Chosen option: "[option 1]"
Reason(s): [e.g., only option which meets criterion | comes out best (see below)].
Positive Consequences
Negative Consequences