Welcome! We love receiving contributions from the community, so thanks for stopping by! There are many ways to contribute, including submitting bug reports, improving documentation, submitting feature requests, reviewing new submissions, or contributing code that can be incorporated into the project.
Some of the information described below is specific to our processes, but most of it is generally useful for GitHub-based open source work.
If you are working on your first open source project or pull request, here are some helpful tutorials:
Table of Contents:
- Code of Conduct
- Finding Something to Work on
- Feature Requests
- Reporting Problems
- Improving Documentation
- Branching
- Pull Request Guidelines
- Style Guidelines
- Further Reading
Code of Conduct
By participating in an Embedded Artistry project, you agree to abide by the Embedded Artistry Code of Conduct.
Finding Something to Work on
The best way to find something to work on is to check the GitHub issue tracker for the project you are interested in. Pick an unassigned issue that you think you can accomplish and add a comment that you are attempting to do it.
If you’re new to a project, or programming in general, keep an eye out for these labels:
good first issuelabeled issues are deemed to be good low-hanging fruit for newcomers to the projecthelp wantedlabeled issues may be more difficult thangood first issueand may include new feature developmentdocumentationlabeled issues apply to new documents or improvements to existing documents
Feature Requests
We welcome feature requests!
For all requests, please file a new GitHub issue in the relevant project. Please provide the details about the feature/function you would like to see and why you need it. If you’re interested in tackling the feature yourself, please discuss your ideas and feedback before proceeding. We may have insights and advice from working on these projects that can benefit your design.
For new features or functions which have not been implemented, please label your request with the “Feature” label. If you are requesting an improvement on an existing function, please use the “Enhancement” label. If you are not a contributor to the project, you may not be able to label issues. It’s fine to stay blank – we’ll label it later.
Small Changes can directly be crafted and submitted directly to a project’s GitHub repository as a Pull Request. See the section regarding Pull Request Submission Guidelines.
Reporting Problems
Before you submit your issue, please search the project’s GitHub Issue archive – maybe your question or issue has already been identified or addressed.
If you find an error in the source code, you can help us by submitting an issue to our GitHub issue tracker. Even better, you can submit a Pull Request with a fix!
Most of our open sourece projects use an issue template, which GitHub will auto-populate when you create a new issue. Please make sure to follow the template and provide the necessary information. This will help us track down the bug as quickly as possible.
For more information about our issue template, please see this article.
Improving Documentation
Should you have a suggestion or correction for the project’s documentation, you can open an issue and outline the problem or improvement. However, creating the documentation fix yourself is extremely helpful!
For larger changes, we recommend creating a new issue (or commenting on a related existing one) to let others know what you’re working on. If you’re making a small change (typo, phrasing) don’t worry about filing an issue first – just open a Pull Request.
Branching
Those users with Contributor permissions can directly clone the repository and work on a branch within it.
Those without Contibutor permissions will need to fork the main repository to work on your changes. Simply navigate to our GitHub page and click the “Fork” button at the top. Once you’ve forked the repository, you can clone your new repository and start making edits.
When using git, it is best to isolate each topic or feature into a “topic branch”. Branches are a great way to group commits related to one feature together, or to isolate different efforts when you might be working on multiple topics at the same time.
While it takes some experience to get the right feel about how to break up commits, a topic branch should be limited in scope to a single issue. If you are working on multiple issues, please create multiple branches and submit them for review separately.
# Checkout the master branch - you want your new branch to come from master
git checkout master
# Create a new branch named newfeature (give your branch its own simple informative name)
git branch newfeature
# Switch to your new branch
git checkout newfeatureFor more information on the GitHub fork and pull-request processes, please see this helpful guide.
Pull Request Guidelines
When you are ready to generate a pull request for preliminary review or merging into the project, you must first push your local topic branch back up to GitHub:
git push origin newfeatureOnce you’ve committed and pushed all of your changes to GitHub:
- Go to the page for your fork on GitHub
- Select your development branch
- Click the pull request button
If you need to make any adjustments to your pull request, just push the updates to your branch. Your pull request will automatically track the changes on your development branch and update.
Please follow the instructions in the Pull Request Template for this project. GitHub will automatically populate the pull request description with this template. For more information on our pull request template, please see this article.
Once you have opened your pull request, it will be processed as described in the Embedded Artistry GitHub Process guide.
Style Guidelines
Many of our projects use automated code formatting with clang-format. Otherwise, please do your best to mimic the existing style of whatever file(s) you are working in.
You can auto-format your code to match the style guidelines by issuing the following command:
make formatFormatting is enforced by the Jenkins build server which runs continuous integration for this project. Your Pull Request will not be accepted if the formatting check fails. If you cannot install clang-format on your machine for some reason, please let us know and we can help you with formatting updates.