This document is a loose guideline showing ways for you to contribute.
If you are unfamiliar with git, the internet is filled with with a wealth of excellent resources. Use whatever you need to become comfortable, these are only some suggestions to get you started. As an absolute first step, any contribution requires you to join GitHub by creating your own account.
Github provides an excellent interactive tutorial to get you ramped up on the basics: Github interactive tutorial
If you want to dive deep and learn the intricacies of git, the Pro Git book is a fantastic read. It includes chapters on how to get started and covers the basics, continues with branching and even includes a chapter specifically on GitHub.
Pull requests are the canonical way of contributing to projects on github. If you have never created a pull request, or want to make sure that you are going about contributing the right way, check out this step-by-step guide.
Commit messages are a central element of contributing to git projects. They provide a history of your work, and well written commit messages are a central resource of well curated git projects. This blog post summarizes what is generally considered good practice for formulating great commit messages.
Opening issues to discuss enhancements is a great way to encourage improvements. Next I've put som suggestions on what you can include in your issue.
- Use a descriptive title summarizing the core improvement you suggest
- Describe the workflow that you wish to add
- Add a use case diagram if you feel that is a good way to present your idea
- Mention other tools that provide features similar to what you would like to see in the project (if applies)
Do whatever you think is necessary to best present your enhancement.
Choose the repository that you think the bug belongs to most, and create an issue there. It is easiest to create a separate issue for every bug that you encounter.
The following is not a mandatory list of information, but a recommendation of what can make sense to include in your issue. Include what you think is crucial to best demonstrate your problem, and help your fellow community members in finding a solution.
- Use a descriptive title that describes the essence of your problem
- Include clear steps to reproduce the problem. Include as much information as possible.
- Provide information about your system, the version you are experiencing problems with, the environment you are using, your operating system etc.
- Explain where and how your experienced behavior differs from what you expected
- Include output to provide more information and context
- Add as much context as possible in any way you see fit and necessary.
If you are unsure about how to create a pull request, this guide should get you on track.
We welcome any contributions that improve the quality of our projects. Be it pull requests for spelling and grammar mistakes or entire enhancements. When creating a pull request, check the project's README.md and CONTRIBUTIONS.md files for possible additional information on what is required to commit code or other changes, such as including unit tests or conforming to the style of the project. The following are suggestions of what can be included in a good pull request.
- Use a descriptive title to present your work
- Make sure all your changes are included and that you did not leave out any changes that you wish to contribute.
- Describe your changes in detail to show your peers exactly what you have contributed
- Include issues in your description if your changes refer to bugs, enhancements or other types of issues
- Conform to the style of the project, such as keeping the same indentation level and brace style
Information on how to develop on a project and how to create builds are usually included in the projects README. If the supplied information is insufficient for you to get started, do not hesitate to create an issue and ask for help. We want to keep the barrier to entry as low as possible.