Create project standards and expectations

When a single person is working on a project there will typically be a consistency imposed simply by the fact that the developer has ‘their way’ of doing things (though this consistency may not exist through time). When multiple developers are working on a project it is good practice to have an agreed up on set of standards that will be followed to ensure that the project has a consistent style and that common practices are followed. These practices can include how/when to test, the branch/develop/merge cycle, documentation formats, as well as code style. A common place to note these standards and expectations is in the CONTRIBUTING.md file in the root of your software project. This file should be considered to be supplementary to the README.md file, and for a slightly different audience. Whilst the README.md file is aimed at users of the software, the CONTRIBUTING.md file is aimed at people who might develop the software, give feedback, or submit bug/feature requests.

Sections to consider for CONTRIBUTING.md

• Welcome and encourage people to contribute to the project
• Table of Contents (especially if the file is long)
• Style guide
  • List standards for code style
  • Consider using a linter and listing it here (with settings)
  • Note the docstring format and guidelines
• Testing
  • Where the tests are located
  • How the test are run
  • The machine/environment on which the tests are expected to pass
• How to submit changes
  • Who can submit changes
  • Expectations for what changes will be accepted
  • The pull request approval process
• How to report a bug
  • What is expected for a good bug report
  • What tags/categories should be used when submitting a report
• How to request an “enhancement”
  • What enhancements are likely to be support and which are not
• Templates
  • Examples for enhancement / bug report / change requests.
• Code of Conduct
  • Expectations for behaviour when contributing to the project
  • Consequences for breaching the code of conduct
  • Email/web address for reporting breaches
• Recognition model
  • Let people know how their contributions will be recognised.
  • The following may be appropriate:
    • An acknowledgement section on the wiki
    • Co-authorship or acknowledgements in a published paper
    • Invitation to join as github contributor
    • A shout out on social media
    • A beverage of choice

The CONTRIBUTING.md file can become quite long if all of the above are included. The key is to have a record of how people should interact with others and with the project and that the project maintainers adhere to these guide lines.