This document describes the Embedded Artistry development process. Following these guidelines shows that you respect the time and effort of the developers managing our open source software projects. In return, you will be shown respect in addressing your issue, reviewing your changes, and incorporating your contributions.
Table of Contents:
git-lfs
Many Embedded Artistry projects store binary artifacts, images, and reference documents using git-lfs. If you do not have git-lfs installed, you will have small (100–200B) placeholder files instead of the actual content. For many projects, this will not be a problem, as the git-lfs files are often images or pdfs. Some projects may store binary files, and these require git-lfs usage.
To install git-lfs on Linux or with WSL:
sudo apt install git-lfsTo install git-lfs on OS X:
brew install git-lfsAdditional installation instructions can be found on the git-lfs website.
Development Process
We do not currently used the widespread NVIE git branching model for our open source projects. Instead, we maintain a much simpler GitHub flow.
For all Embedded Artistry projects, master contains the latest code. The master branch shall always remain in a usable state. Changes which render the master branch unusable will be immediately corrected or reverted.
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 newfeaturePlease create your branch from master when making any new changes. Once you are ready to merge changes, open a pull request. The build server will test and analyze the branch to ensure it can be safely merged.
Forking
Note: Members with write access can make branches directly in the repository. Creating a fork is optional in this case.
You 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.
For more information on creating a fork and submitting a PR using a fork, please see this helpful guide.
Protected Branches
The master branch is marked as “protected” for most of our projects. Changes cannot be submitted to the master branch unless the proper process is followed:
- Changes cannot be pushed directly to master; a PR must be opened
- The Continuous Integration (CI) server must verify that the changes satisfy our code quality processes
- The code must be reviewed.
These protections apply to all contributors, including administrators.
Commit Requirements
Please see our Source Code Commit Guidelines for information on structuring your commits and commit messages.
In general:
- Commits should be “atomic”, which means all changes are related and accomplish a single goal
- Avoid large commits with lots of changes
- Include a subject line that summarizes the change
- In the commit body, describe why you’re making the change and what it is supposed to accomplish
Continuous Integration
We strive to utilize continuous integration (CI) on all of our projects. We maintain a Jenkins build server that runs automated checks for Embedded Artistry organization projects.
The CI process is automatically launched when:
- A pull request is opened
- A new commit is pushed to a pull request
- A new commit is pushed to master
Many of our projects will upload test results and code annotations to the GitHub pull request using Report.CI. This allows you to view test failures within the GitHub interface.
For more information about our CI process, see this Field Atlas entry.
Submitting Changes
All changes to Embedded Artistry open source projects shall be handled through the pull request process. If you are new to pull requests, please see our Open Source Contribution guide.
Please fill out the pull request template when populating the PR body. This helps provide the proper context for maintainers and reviewers. Additionally, the manual checklist helps eliminate common errors prior to code reviews.
Once you open a Pull Request, the CI process will automatically kick off. The build server will report either successful or failed status checks. You will see something similar to the following:
Here is what a successful CI build looks like: If the status checks fail, you must resolve the issues. Please tag @phillipjohnston in your PR if you cannot see why your build failed.
Once the CI status checks pass, your changes will be reviewed by a project maintainer.
When all of the steps are complete, your PR will be merged.
Code Review Requirements
Your changes will be reviewed before they are accepted. Before reviews begin, changes must build correctly on the Jenkins CI server, be free of formatting errors, and pass tests.
Project maintainers will reveiw your changes and provide feedback. We work on a variety of projects, so please expect some delay in getting back to you with a code review. I will notify you as soon as I have seen the PR and provide insight into the expected review timeline.
If you are a new code reviewer or contributor, please see the Field Atlas entry on Giving and Receiving Feedback.
Addressing Feedback
During the review, constructive feedback may be provided by the project maintainers. Feedback isn’t meant as an attack, but to help make sure the highest-quality code makes it into our project. Changes will be approved once required feedback has been addressed.
Rebasing and Updating
If a maintainer asks you to “rebase” your PR, they’re saying that a lot of code has changed on master since you created your branch/fork. You need to update your branch/fork with the latest changes from master so it is easier to merge.
If you are working from the primary repository, you need to update master and then rebase your changes onto it.
git checkout master
git pull
git checkout -
git rebase masterIf you’ve forked the repository, you will need to add the primary repository as a “remote” so you can pull in changes. You can also update your fork directly in GitHub using the Pull Request interface.
To add the primary repository to your fork as another “remote”, follow these steps:
git remote add upstream <https://github.com/organization/project>Note: You only need to do this once.
To update your forked repository from the command line, follow these steps:
# Fetch upstream master and merge with your repo's master branch
git fetch upstream
git checkout master
git merge upstream/master
# An alternate for the last step, which throws away any changes on
# your copy of master and replaces it with the original project's master branch
git reset upstream/master --hard
# Now, rebase your development branch
git checkout newfeature
git rebase masterIf too much code has changed for git to automatically apply your branches changes to the new master, you will need to manually resolve the merge conflicts yourself.
Once your new branch has no conflicts and works correctly, you can override your old branch using this command:
git push -fNote that this will overwrite the old branch on the server, so make sure you are happy with your changes first!
If you have any questions about this process, please ask for help!
CCC Process
Occasionally, projects enter a period of high scrutiny, especially before a new release. During these periods, the Code Change Control (CCC) process is enacted. You may see a new pull request template during those periods.
The CCC PR template provides much more rigor and documentation than a normal PR message. When we need stability and strict testing, such as when attempting to stabilize for a customer release, the CCC process helps ensure that we include changes that are thoroughly tested and justified.
Please understand that this process is not meant to keep you out, but to ensure that changes are sufficiently vetted before they are accepted.