👍🎉 First off, thanks for taking the time to contribute! 🎉👍
This document outlines a generic process of contributing and applies to all CHAOSS repositories. Each repository may have unique guidelines specific to the project, but this document serves as a primer for what is required when contributing to CHAOSS.
Use your best judgement, and feel free to propose changes to this document in a pull request
Anyone can contribute to CHAOSS on any of our communication channels. See https://chaoss.community/participate/ to learn more about how to participate. We are excited to meet first-timers and we are always ready to support you during your contribution journey.
CHAOSS uses the following channels for contributions:
- Mailing Lists
- Community calls
- Working group calls
- GitHub
- CHAOSS on the Web
- CHAOSS on GitHub
- CHAOSS on LFX Crowdfunding
- CHAOSS on Open Collective
- CHAOSS Podcast
- CHAOSS on YouTube
- CHAOSS on Twitter
- CHAOSS on LinkedIn
Strategic directions, clarifications of scope, and ideas in an early stage are best discussed on the mailing list, calls, and face-to-face meetings. See https://chaoss.community/participate/.
Bug reports and specific feature requests are best discussed in an issue on the repository they pertain to. You can do this by creating an issue and explaining what bug you found in the comment section. The conversation moves from there.
Changes can be made from within the GitHub user interface. As a non-maintainer, GitHub will create a fork under your name and ask that you create a pull request. The pull request lets the repository maintainers know of your change and provides a space to discuss the change.
The CHAOSS Charter requires that contributions
are accompanied by a Developer Certificate of Origin sign-off.
For ensuring it, a bot checks all incoming commits.
A DCO sign-off is accomplished by writing into the commit comment field:
Signed-off-by: Your Name <[email protected]>
It should be noted that the angled brackets < and > need to be included with the email.
This can be automated by using a browser plugin like DCO GitHub UI.
The DCO browser plugin is a handy tool to automatically sign commits created using GitHub. To enable this plugin:
-
Go to the plugin page on the chrome web store.
-
Alternatively, you could go to the firefox addon page to add the extension to your browser.
-
Once you add the extension, right click on the extension in the toolbar of your browser and select
Options. -
A dialog box will open up as shown below. Fill in your GitHub name (not the handle) and email-id.
-
Then, whenever you perform a commit on GitHub, the line
Signed-off-by: Your Name <Youremail>will automatically appear in the commit description while making changes to a file as shown in the example below. A commit message can be added to the lines above the auto-generated sign-off. -
Once you perform the commit and send a pull request, the commit will be verified and approved by the DCO bot.
This plugin is non-intrusive and works only on GitHub.
If you forget to add the sign-off you can also amend a previous commit with the sign-off. For this, you need to clone the repository on your local machine and run git commit --amend -s. Because you have pushed your changes to GitHub already you'll need to force push your branch after this with git push -f.
Changes to source code files or documents are best contributed and discussed in pull requests. Please look at the CONTRIBUTING.md files for repository specifics.
In this process, make sure your GitHub account is setup fork then locally clone the repo:
git clone [email protected]:<your-username>/<repository>.git
Create a feature branch in your local repository:
git checkout -b <branch>
Make your change and commit the change (NOTE: with -s you sign-off on each commit, which is your Developer Certificate of Origin):
git add <changed file>
git commit -s -m "<description of change>"
If you forget to add the sign-off you can also amend a previous commit with the sign-off by running git commit --amend -s. If you have pushed your changes to GitHub already you'll need to force push your branch after this with git push -f.
Push to your fork on GitHub:
git push origin <branch>
Then, submit a pull request on GitHub to the CHAOSS repository.
- Check if your code addition will pass both code linting checks and unit tests.
- Check if your documentation commits are free from typos.
- Ensure your commit messages are descriptive. How to Write a Git Commit Message explains how to write good commit messages.
- Check the commits and commits messages and ensure they are free from typos.
At this point, you are waiting on the CHAOSS repository maintainers. They will comment on your pull requests within three business days (and, typically, one business day).
The CHAOSS repository maintainers will report on open issues and pull requests on the calls and via the mailing list to elicit feedback from the community.
The README.md of the repository contains a list of maintainers. Each CHAOSS repository brings together different people and they document in the repository-specific CONTRIBUTING.md how someone becomes a maintainer on their repository.
CHAOSS repository maintainers tag commits on the master branch as releases (snapshots). Each CHAOSS repository has its own release cadence. Between releases, the master branch is under development.
The basic decision-making mechanism for CHAOSS is a lazy consensus that occurs on the relevant mailing list. Each of the software projects or working groups will try to reach a consensus on their decisions, after giving a reasonable opportunity to people contributing to them to express their opinion. When a discussion about a decision happens outside of the mailing list in the periodic calls or other communication channels, a proposal for a decision will be sent to the appropriate mailing list(s). The decision should be finalized on the mailing list using lazy consensus after giving people who were not in the discussion time to review, comment, and participate.
When the issues under discussion are perceived to be of importance to the whole CHAOSS community, the same process will be carried on at the CHAOSS level, using the general periodic calls and other communication means for discussion with the final decision being made on the mailing list using lazy consensus.
If consensus is not reached, the issue may be raised to the CHAOSS board, where consensus and voting may be used to get a final decision on the matter.
In any case, all decisions are subject to the CHAOSS Charter.
Note: By "lazy consensus" we mean, as Apache does a decision-making policy that assumes general consent if no responses are posted within a defined period. For example, "I'm going to commit this by lazy consensus if no-one objects within the next three days."