Contribution Guidelines

4 minute read

v1.0.0 - Last updated 2018-07-08

This post is not really a post as the other posts but rather a document which will be updated from time to time. The document contains the general contribution guidelines of open source projects made by me or my company Jitesoft.

Opensource software should always have contribution guidelines, mainly to make it clear where the repository maintainers have in mind when it comes to how to behave in the community.
In my case, I have consen to use a code of conduct which is already used by many others, it’s called the Contributor Covenant and mainly contains a brief ruleset of behaviour and what is seen as accepted and none-accepted behaviour when it comes to contributions.

There might be more narrowed down rules in some projects, but the following is the general gist of it.

Code of conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints and experiences
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

  • The use of sexualized language or imagery and unwelcome sexual attention or advances
  • Trolling, insulting/derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others’ private information, such as a physical or electronic address, without explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected] All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

How to contribute

Bug reporting

Use the issue handler in the repository. Always check the existing issues to make sure it has not already been submitted.
When creating a bug report, please include as much information as possible, what version you used, what happened, what did you expect to happen. Any exceptions or error logs that might be relevant can be important.
If possible, create a short reproducible case so that anyone whom tries to fix the bug can reproduce the issue.

Suggestions

As with bugs, the issue handler is used for suggestions. Be sure to mark the issue with the suggestion tag so that it does not bloat the issue handler with un-tagged issues.
Make sure that there is no existing issue with the same suggestion and include as much information as possible to make it easy to understand.
Use a good title and explain why the suggestion would make the project better.

Pull/Merge -requests

Code contributions are welcome, but they need to follow a set of guidelines so that they are easy to integrate with the current codebase.
When creating a new request, be sure to include the issue that it resolves in the body text of the request. Make the title descriptive and explain what and why your changes does.
Follow the code style and test coverage requirements below.

Guidelines and standards

Code standard

Depending on the project, different code standards are used. Most projects include a specific codestandard file (style.xml for php projects) or information on how to install specific code standards if such is used. Check the readme.
All code should pass any codestandard tests in the build script.

Test coverage

Test coverage of new code should be as high as possible. We might not deny a request with 90% coverage, but we aim at 100% coverage at all time.

Additional notes

This document might (and will likely) be updated with additional information. If so, there will be a notification in the readme file.