We are a community effort, and everybody is most welcome to participate! You do not have to be listed on the Jazz Community page to be considered a member. Be it filing bugs, formulating enhancements, creating pull requests, or any other means of contribution, we encourage contributions from everyone. We are looking forward to collaborating with all fellow jazz users.
This document is a loose guideline showing ways for you to contribute.
- Git
- Suggesting enhancements
- Reporting bugs
- Submitting pull requests
- Including your project
- Becoming a member
- Getting in touch
- Improving this document
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.
Our goal is to improve the Jazz platform together with you, and we need your ideas and input to keep on improving. Opening issues to discuss enhancements is a great way to encourage improvement as a community. Open an issue where you feel it fits best. To get the most out of your enhancements, we have some 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
- Include screenshots or mockups if you have UI enhancements
- Mention other tools that provide features similar to what you would like to see in the project
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 screenshots 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.
Our preliminary goal was to establish the jazz-community organization as the preferred way to get access to published Jazz extensions. There are already a few extensions milling around the web, but most of them are either only source code or just a compiled artifact. Therefore, we would gladly welcome other projects into the jazz-community. There are multiple ways to include your project:
If you already have an awesome repository that would be well suited for the jazz-community organization, we can take the necessary steps to move your repository into the jazz-community organization together. To ensure a certain amount of quality and consistency across the entire organization, we assume the following to be met:
- The project is actively maintained and you will continue to actively maintain the repository in the near future
- The
CONTRIBUTING.mdfile of your repository must derive from this contribution guide. Hence, your repository should apply these guidelines today or you should be willing to follow them from now onward - Your project has an appropriate
LICENSEandREADME.mdfile - You have applied common software engineering practices to ensure readability and maintainability of the source code
- Continuous Integration is available where possible. The build is automated on Travis CI and the releases are pushed back to the GitHub Releases page if a build contains a new git tag (e.g. v1.2.0).
Please get in touch with one of our Org Admins to discuss the details.
If you prefer to keep your repository as part of your user profile or within your companies GitHub organization, we can still mention your project as part of our Other useful Repositories list. If you want to be mentioned there, just send us a Pull Request with your additions to the list.
All jazz-community projects are public, so you can contribute to any repository through pull requests. Every repository has an owning team associated which will drive the project, merge pull requests, and manage releases. If you want to become a core member of a project, open an issue within that repository and express your wish. To ensure the quality of our projects, you may have to fulfill one of the following requirements:
- You have proven your skills by contributing high quality pull requests within that repository in the past
- You are endorsed by an existing core member to join
- You have proven your skills in another open source project and you agree with the project vision of the existing members
If your project is about to be moved to the jazz-community organization, you will remain core member of that repository.
The only way to get in touch with us at the moment is to open an Issue in one of the repositories. We do not have any chat room like Slack or Gitter for informal exchange as of now, so you can open an Issue if you have a question even if it not necessarily is a potential issue.
This contribution guideline is subject to the conditions that are described here. If you have suggestions for improvement, open an issue or create a pull request!