mirror of
https://git.yoctoproject.org/poky
synced 2026-09-19 09:49:33 +02:00
dev-manual, ref-manual: Moved "Workflows" section to ref-manual
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
committed by
Richard Purdie
Richard Purdie
parent
d17632463e
commit
c7969c64bb
@@ -129,7 +129,7 @@ TARFILES = dev-style.css dev-manual.html \
|
|||||||
else
|
else
|
||||||
TARFILES = dev-style.css dev-manual.html \
|
TARFILES = dev-style.css dev-manual.html \
|
||||||
figures/bsp-dev-flow.png \
|
figures/bsp-dev-flow.png \
|
||||||
figures/dev-title.png figures/git-workflow.png \
|
figures/dev-title.png \
|
||||||
figures/kernel-dev-flow.png \
|
figures/kernel-dev-flow.png \
|
||||||
figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
|
figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
|
||||||
figures/recipe-workflow.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/analysis-for-package-splitting.png figures/image-generation.png \
|
||||||
figures/sdk-generation.png figures/building-an-image.png \
|
figures/sdk-generation.png figures/building-an-image.png \
|
||||||
figures/build-workspace-directory.png figures/source-repos.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
|
MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
|
||||||
FIGURES = figures
|
FIGURES = figures
|
||||||
STYLESHEET = $(DOC)/*.css
|
STYLESHEET = $(DOC)/*.css
|
||||||
|
|||||||
@@ -617,154 +617,6 @@
|
|||||||
</section>
|
</section>
|
||||||
</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'>
|
<section id='submitting-a-defect-against-the-yocto-project'>
|
||||||
<title>Submitting a Defect Against the Yocto Project</title>
|
<title>Submitting a Defect Against the Yocto Project</title>
|
||||||
|
|
||||||
|
|||||||
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
@@ -65,6 +65,197 @@
|
|||||||
</para>
|
</para>
|
||||||
</section>
|
</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'>
|
<section id='yocto-project-repositories'>
|
||||||
<title>Yocto Project Source Repositories</title>
|
<title>Yocto Project Source Repositories</title>
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user