This section provides workflow concepts using the Yocto Project and Git. In particular, the information covers basic practices that describe roles and actions in a collaborative development environment.
The Yocto Project files are maintained using Git in "master" branches whose Git histories track every change and whose structures provides branches for all diverging functionality. Although there is no need to use Git, many open source projects do so.
For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" branch of a given Git repository. The "master" branch is the “upstream” repository from which final or most recent builds of the project occur. The maintainer is responsible for accepting changes from other developers and for organizing the underlying branch structure to reflect release strategies and so forth.
The Yocto Project poky
Git repository also has an
upstream contribution Git repository named
poky-contrib
.
You can see all the branches in this repository using the web interface
of the
Source Repositories organized
within the "Poky Support" area.
These branches temporarily hold changes to the project that have been
submitted or committed by the Yocto Project development team and by
community members who contribute to the project.
The maintainer determines if the changes are qualified to be moved
from the "contrib" branches into the "master" branch of the Git
repository.
Developers (including contributing community members) create and maintain cloned repositories of the upstream "master" branch. The cloned repositories are local to their development platforms and are used to develop changes. When a developer is satisfied with a particular feature or change, they "push" the changes to the appropriate "contrib" repository.
Developers are responsible for keeping their local repository up-to-date with "master". They are also responsible for straightening out any conflicts that might arise within files that are being worked on simultaneously by more than one person. All this work is done locally on the developer’s machine before anything is pushed to a "contrib" area and examined at the maintainer’s level.
A somewhat formal method exists by which developers commit changes and push them into the "contrib" area and subsequently request that the maintainer include them into "master". This process is called “submitting a patch” or "submitting a change." For information on submitting patches and changes, see the "Submitting a Change to the Yocto Project" section in the Yocto Project Development Tasks Manual.
To summarize the development workflow: a single point of entry exists for changes into the project’s "master" branch of the Git repository, which is controlled by the project’s maintainer. And, a set of developers exist who independently develop, test, and submit changes to "contrib" areas for the maintainer to examine. The maintainer then chooses which changes are going to become a permanent part of the project.
While each development environment is unique, there are some best practices or methods that help development run smoothly. The following list describes some of these practices. For more information about Git workflows, see the workflow topics in the Git Community Book.
Make Small Changes: It is best to keep the changes you commit small as compared to bundling many disparate changes into a single commit. This practice not only keeps things manageable but also allows the maintainer to more easily include or refuse changes.
It is also good practice to leave the repository in a state that allows you to still successfully build your project. In other words, do not commit half of a feature, then add the other half as a separate, later commit. Each commit should take you from one buildable project state to another buildable state.
Use Branches Liberally: It is very easy to create, use, and delete local branches in your working Git repository. You can name these branches anything you like. It is helpful to give them names associated with the particular feature or change on which you are working. Once you are done with a feature or change and have merged it into your local master branch, simply discard the temporary branch.
Merge Changes:
The git merge
command allows you to take
the changes from one branch and fold them into another branch.
This process is especially helpful when more than a single
developer might be working on different parts of the same
feature.
Merging changes also automatically identifies any collisions
or "conflicts" that might happen as a result of the same lines
of code being altered by two different developers.
Manage Branches: Because branches are easy to use, you should use a system where branches indicate varying levels of code readiness. For example, you can have a "work" branch to develop in, a "test" branch where the code or change is tested, a "stage" branch where changes are ready to be committed, and so forth. As your project develops, you can merge code across the branches to reflect ever-increasing stable states of the development.
Use Push and Pull:
The push-pull workflow is based on the concept of developers
"pushing" local commits to a remote repository, which is
usually a contribution repository.
This workflow is also based on developers "pulling" known
states of the project down into their local development
repositories.
The workflow easily allows you to pull changes submitted by
other developers from the upstream repository into your
work area ensuring that you have the most recent software
on which to develop.
The Yocto Project has two scripts named
create-pull-request
and
send-pull-request
that ship with the
release to facilitate this workflow.
You can find these scripts in the scripts
folder of the
Source Directory.
For information on how to use these scripts, see the
"Using Scripts to Push a Change Upstream and Request a Pull"
section in the Yocto Project Development Tasks Manual.
Patch Workflow:
This workflow allows you to notify the maintainer through an
email that you have a change (or patch) you would like
considered for the "master" branch of the Git repository.
To send this type of change, you format the patch and then
send the email using the Git commands
git format-patch
and
git send-email
.
For information on how to use these scripts, see the
"Submitting a Change to the Yocto Project"
section in the Yocto Project Development Tasks Manual.