CaROS/poky
3
1
Fork 0
mirror of https://git.yoctoproject.org/git/poky synced 2026-01-04 16:10:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

dev-manual, ref-manual: Moved "Workflows" section to ref-manual

Browse Source 
Fixes [YOCTO #11630]

I moved the "Workflows" section to the ref-manual.  This section is
primarily concepts and needs to be out of the dev-manual, which
is being reconstituted into a "how-to" manual.

(From yocto-docs rev: 2f8bfaac3da9e2d7042ea381a3e8957f96b5bf5a)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2017-06-15 09:11:09 -07:00 committed by Richard Purdie
parent d17632463e
commit c7969c64bb
4 changed files with 193 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
documentation/Makefile
View File

@ -129,7 +129,7 @@ TARFILES = dev-style.css dev-manual.html \
else
TARFILES = dev-style.css dev-manual.html \
figures/bsp-dev-flow.png \
figures/dev-title.png figures/git-workflow.png \
figures/dev-title.png \
figures/kernel-dev-flow.png \
figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
figures/recipe-workflow.png \
@ -271,7 +271,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
figures/analysis-for-package-splitting.png figures/image-generation.png \
figures/sdk-generation.png figures/building-an-image.png \
figures/build-workspace-directory.png figures/source-repos.png \
figures/index-downloads.png figures/yp-download.png
figures/index-downloads.png figures/yp-download.png figures/git-workflow.png
MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
FIGURES = figures
STYLESHEET = $(DOC)/*.css

148
documentation/dev-manual/dev-manual-newbie.xml
View File

@ -617,154 +617,6 @@
</section>
</section>
<section id='workflows'>
<title>Workflows</title>
<para>
This section provides some overview on workflows using Git.
In particular, the information covers basic practices that describe roles and actions in a
collaborative development environment.
Again, if you are familiar with this type of development environment, you might want to just
skip this section.
</para>
<para>
The Yocto Project files are maintained using Git in a "master" branch whose Git history
tracks every change and whose structure 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 where the final 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.
<note>For information on finding out who is responsible for (maintains)
a particular area of code, see the
"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
section.
</note>
</para>
<para>
The project also has an upstream contribution Git repository named
<filename>poky-contrib</filename>.
You can see all the branches in this repository using the web interface
of the
<ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> 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.
</para>
<para>
Developers (including contributing community members) create and maintain cloned repositories
of the upstream "master" branch.
These 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.
</para>
<para>
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 machines before anything is pushed to a
"contrib" area and examined at the maintainer’s level.
</para>
<para>
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
"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section.
</para>
<para>
To summarize the environment: 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.
</para>
<para>
<imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
</para>
<para>
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
<ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
<itemizedlist>
<listitem><para><emphasis>Make Small Changes:</emphasis> 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.</para>
<para>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.</para></listitem>
<listitem><para><emphasis>Use Branches Liberally:</emphasis> 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.</para></listitem>
<listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
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.</para></listitem>
<listitem><para><emphasis>Manage Branches:</emphasis> 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.</para></listitem>
<listitem><para><emphasis>Use Push and Pull:</emphasis> 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 <filename>create-pull-request</filename> and
<filename>send-pull-request</filename> that ship with the release to facilitate this
workflow.
You can find these scripts in the <filename>scripts</filename>
folder of the
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
For information on how to use these scripts, see the
"<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.
</para></listitem>
<listitem><para><emphasis>Patch Workflow:</emphasis> 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
<filename>git format-patch</filename> and <filename>git send-email</filename>.
For information on how to use these scripts, see the
"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
section.
</para></listitem>
</itemizedlist>
</para>
</section>
<section id='submitting-a-defect-against-the-yocto-project'>
<title>Submitting a Defect Against the Yocto Project</title>

0
documentation/dev-manual/figures/git-workflow.png → documentation/ref-manual/figures/git-workflow.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

191
documentation/ref-manual/ref-development-environment.xml
View File

@ -65,6 +65,197 @@
</para>
</section>
<section id='workflows'>
<title>Workflows</title>
<para>
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.
<note>
If you are familiar with this type of development environment, you
might not want to read this section.
</note>
</para>
<para>
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.
<para>
</para>
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.
<note>For information on finding out who is responsible for (maintains)
a particular area of code, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
section of the Yocto Project Development Manual.
</note>
</para>
<para>
The Yocto Project <filename>poky</filename> Git repository also has an
upstream contribution Git repository named
<filename>poky-contrib</filename>.
You can see all the branches in this repository using the web interface
of the
<ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> 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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
section in the Yocto Project Development Manual.
</para>
<para>
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.
</para>
<para>
<imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
</para>
<para>
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
<ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
<itemizedlist>
<listitem><para>
<emphasis>Make Small Changes:</emphasis>
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.</para>
<para>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.
</para></listitem>
<listitem><para>
<emphasis>Use Branches Liberally:</emphasis>
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.
</para></listitem>
<listitem><para>
<emphasis>Merge Changes:</emphasis>
The <filename>git merge</filename> 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.
</para></listitem>
<listitem><para>
<emphasis>Manage Branches:</emphasis>
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.
</para></listitem>
<listitem><para>
<emphasis>Use Push and Pull:</emphasis>
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
<filename>create-pull-request</filename> and
<filename>send-pull-request</filename> that ship with the
release to facilitate this workflow.
You can find these scripts in the <filename>scripts</filename>
folder of the
<link linkend='source-directory'>Source Directory</link>.
For information on how to use these scripts, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>"
section in the Yocto Project Development Manual.
</para></listitem>
<listitem><para>
<emphasis>Patch Workflow:</emphasis>
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
<filename>git format-patch</filename> and
<filename>git send-email</filename>.
For information on how to use these scripts, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
section in the Yocto Project Development Manual.
</para></listitem>
</itemizedlist>
</para>
</section>
<section id='yocto-project-repositories'>
<title>Yocto Project Source Repositories</title>