summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-15 09:11:09 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-06-22 09:16:43 +0100
commitc7969c64bb1d8b667efc3c3abe48f9e1bec1d1f2 (patch)
tree66f510cf2d98def9f5858f3004b0a5e1d42af186 /documentation
parentd17632463e2d54c91ef9b334c14e5067b8171b4b (diff)
downloadpoky-c7969c64bb1d8b667efc3c3abe48f9e1bec1d1f2.tar.gz
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>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/Makefile4
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml148
-rw-r--r--documentation/ref-manual/figures/git-workflow.png (renamed from documentation/dev-manual/figures/git-workflow.png)bin26586 -> 26586 bytes
-rw-r--r--documentation/ref-manual/ref-development-environment.xml191
4 files changed, 193 insertions, 150 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index 131c0b7f33..6a2f22e40e 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -129,7 +129,7 @@ TARFILES = dev-style.css dev-manual.html \
129 else 129 else
130TARFILES = dev-style.css dev-manual.html \ 130TARFILES = dev-style.css dev-manual.html \
131 figures/bsp-dev-flow.png \ 131 figures/bsp-dev-flow.png \
132 figures/dev-title.png figures/git-workflow.png \ 132 figures/dev-title.png \
133 figures/kernel-dev-flow.png \ 133 figures/kernel-dev-flow.png \
134 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ 134 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
135 figures/recipe-workflow.png \ 135 figures/recipe-workflow.png \
@@ -271,7 +271,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
271 figures/analysis-for-package-splitting.png figures/image-generation.png \ 271 figures/analysis-for-package-splitting.png figures/image-generation.png \
272 figures/sdk-generation.png figures/building-an-image.png \ 272 figures/sdk-generation.png figures/building-an-image.png \
273 figures/build-workspace-directory.png figures/source-repos.png \ 273 figures/build-workspace-directory.png figures/source-repos.png \
274 figures/index-downloads.png figures/yp-download.png 274 figures/index-downloads.png figures/yp-download.png figures/git-workflow.png
275MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 275MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
276FIGURES = figures 276FIGURES = figures
277STYLESHEET = $(DOC)/*.css 277STYLESHEET = $(DOC)/*.css
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index aca292063e..c2147b39e7 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -617,154 +617,6 @@
617 </section> 617 </section>
618</section> 618</section>
619 619
620<section id='workflows'>
621 <title>Workflows</title>
622
623 <para>
624 This section provides some overview on workflows using Git.
625 In particular, the information covers basic practices that describe roles and actions in a
626 collaborative development environment.
627 Again, if you are familiar with this type of development environment, you might want to just
628 skip this section.
629 </para>
630
631 <para>
632 The Yocto Project files are maintained using Git in a "master" branch whose Git history
633 tracks every change and whose structure provides branches for all diverging functionality.
634 Although there is no need to use Git, many open source projects do so.
635 For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
636 branch of a given Git repository.
637 The "master" branch is the “upstream” repository where the final builds of the project occur.
638 The maintainer is responsible for accepting changes from other developers and for
639 organizing the underlying branch structure to reflect release strategies and so forth.
640 <note>For information on finding out who is responsible for (maintains)
641 a particular area of code, see the
642 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
643 section.
644 </note>
645 </para>
646
647 <para>
648 The project also has an upstream contribution Git repository named
649 <filename>poky-contrib</filename>.
650 You can see all the branches in this repository using the web interface
651 of the
652 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
653 within the "Poky Support" area.
654 These branches temporarily hold changes to the project that have been
655 submitted or committed by the Yocto Project development team and by
656 community members who contribute to the project.
657 The maintainer determines if the changes are qualified to be moved
658 from the "contrib" branches into the "master" branch of the Git
659 repository.
660 </para>
661
662 <para>
663 Developers (including contributing community members) create and maintain cloned repositories
664 of the upstream "master" branch.
665 These repositories are local to their development platforms and are used to develop changes.
666 When a developer is satisfied with a particular feature or change, they "push" the changes
667 to the appropriate "contrib" repository.
668 </para>
669
670 <para>
671 Developers are responsible for keeping their local repository up-to-date with "master".
672 They are also responsible for straightening out any conflicts that might arise within files
673 that are being worked on simultaneously by more than one person.
674 All this work is done locally on the developer’s machines before anything is pushed to a
675 "contrib" area and examined at the maintainer’s level.
676 </para>
677
678 <para>
679 A somewhat formal method exists by which developers commit changes and push them into the
680 "contrib" area and subsequently request that the maintainer include them into "master"
681 This process is called “submitting a patch” or "submitting a change."
682 For information on submitting patches and changes, see the
683 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section.
684 </para>
685
686 <para>
687 To summarize the environment: a single point of entry exists for
688 changes into the project’s "master" branch of the Git repository,
689 which is controlled by the project’s maintainer.
690 And, a set of developers exist who independently develop, test, and
691 submit changes to "contrib" areas for the maintainer to examine.
692 The maintainer then chooses which changes are going to become a
693 permanent part of the project.
694 </para>
695
696 <para>
697 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
698 </para>
699
700 <para>
701 While each development environment is unique, there are some best practices or methods
702 that help development run smoothly.
703 The following list describes some of these practices.
704 For more information about Git workflows, see the workflow topics in the
705 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
706 <itemizedlist>
707 <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit
708 small as compared to bundling many disparate changes into a single commit.
709 This practice not only keeps things manageable but also allows the maintainer
710 to more easily include or refuse changes.</para>
711 <para>It is also good practice to leave the repository in a state that allows you to
712 still successfully build your project. In other words, do not commit half of a feature,
713 then add the other half as a separate, later commit.
714 Each commit should take you from one buildable project state to another
715 buildable state.</para></listitem>
716 <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
717 delete local branches in your working Git repository.
718 You can name these branches anything you like.
719 It is helpful to give them names associated with the particular feature or change
720 on which you are working.
721 Once you are done with a feature or change and have merged it
722 into your local master branch, simply discard the temporary
723 branch.</para></listitem>
724 <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
725 command allows you to take the
726 changes from one branch and fold them into another branch.
727 This process is especially helpful when more than a single developer might be working
728 on different parts of the same feature.
729 Merging changes also automatically identifies any collisions or "conflicts"
730 that might happen as a result of the same lines of code being altered by two different
731 developers.</para></listitem>
732 <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should
733 use a system where branches indicate varying levels of code readiness.
734 For example, you can have a "work" branch to develop in, a "test" branch where the code or
735 change is tested, a "stage" branch where changes are ready to be committed, and so forth.
736 As your project develops, you can merge code across the branches to reflect ever-increasing
737 stable states of the development.</para></listitem>
738 <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the
739 concept of developers "pushing" local commits to a remote repository, which is
740 usually a contribution repository.
741 This workflow is also based on developers "pulling" known states of the project down into their
742 local development repositories.
743 The workflow easily allows you to pull changes submitted by other developers from the
744 upstream repository into your work area ensuring that you have the most recent software
745 on which to develop.
746 The Yocto Project has two scripts named <filename>create-pull-request</filename> and
747 <filename>send-pull-request</filename> that ship with the release to facilitate this
748 workflow.
749 You can find these scripts in the <filename>scripts</filename>
750 folder of the
751 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
752 For information on how to use these scripts, see the
753 "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.
754 </para></listitem>
755 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
756 maintainer through an email that you have a change (or patch) you would like considered
757 for the "master" branch of the Git repository.
758 To send this type of change, you format the patch and then send the email using the Git commands
759 <filename>git format-patch</filename> and <filename>git send-email</filename>.
760 For information on how to use these scripts, see the
761 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
762 section.
763 </para></listitem>
764 </itemizedlist>
765 </para>
766</section>
767
768<section id='submitting-a-defect-against-the-yocto-project'> 620<section id='submitting-a-defect-against-the-yocto-project'>
769 <title>Submitting a Defect Against the Yocto Project</title> 621 <title>Submitting a Defect Against the Yocto Project</title>
770 622
diff --git a/documentation/dev-manual/figures/git-workflow.png b/documentation/ref-manual/figures/git-workflow.png
index e401330a12..e401330a12 100644
--- a/documentation/dev-manual/figures/git-workflow.png
+++ b/documentation/ref-manual/figures/git-workflow.png
Binary files differ
diff --git a/documentation/ref-manual/ref-development-environment.xml b/documentation/ref-manual/ref-development-environment.xml
index 5b0557d905..08e790b7a2 100644
--- a/documentation/ref-manual/ref-development-environment.xml
+++ b/documentation/ref-manual/ref-development-environment.xml
@@ -65,6 +65,197 @@
65 </para> 65 </para>
66</section> 66</section>
67 67
68<section id='workflows'>
69 <title>Workflows</title>
70
71 <para>
72 This section provides workflow concepts using the Yocto Project and
73 Git.
74 In particular, the information covers basic practices that describe
75 roles and actions in a collaborative development environment.
76 <note>
77 If you are familiar with this type of development environment, you
78 might not want to read this section.
79 </note>
80 </para>
81
82 <para>
83 The Yocto Project files are maintained using Git in "master"
84 branches whose Git histories track every change and whose structures
85 provides branches for all diverging functionality.
86 Although there is no need to use Git, many open source projects do so.
87 <para>
88
89 </para>
90 For the Yocto Project, a key individual called the "maintainer" is
91 responsible for the "master" branch of a given Git repository.
92 The "master" branch is the “upstream” repository from which final or
93 most recent builds of the project occur.
94 The maintainer is responsible for accepting changes from other
95 developers and for organizing the underlying branch structure to
96 reflect release strategies and so forth.
97 <note>For information on finding out who is responsible for (maintains)
98 a particular area of code, see the
99 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
100 section of the Yocto Project Development Manual.
101 </note>
102 </para>
103
104 <para>
105 The Yocto Project <filename>poky</filename> Git repository also has an
106 upstream contribution Git repository named
107 <filename>poky-contrib</filename>.
108 You can see all the branches in this repository using the web interface
109 of the
110 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
111 within the "Poky Support" area.
112 These branches temporarily hold changes to the project that have been
113 submitted or committed by the Yocto Project development team and by
114 community members who contribute to the project.
115 The maintainer determines if the changes are qualified to be moved
116 from the "contrib" branches into the "master" branch of the Git
117 repository.
118 </para>
119
120 <para>
121 Developers (including contributing community members) create and
122 maintain cloned repositories of the upstream "master" branch.
123 The cloned repositories are local to their development platforms and
124 are used to develop changes.
125 When a developer is satisfied with a particular feature or change,
126 they "push" the changes to the appropriate "contrib" repository.
127 </para>
128
129 <para>
130 Developers are responsible for keeping their local repository
131 up-to-date with "master".
132 They are also responsible for straightening out any conflicts that
133 might arise within files that are being worked on simultaneously by
134 more than one person.
135 All this work is done locally on the developer’s machine before
136 anything is pushed to a "contrib" area and examined at the maintainer’s
137 level.
138 </para>
139
140 <para>
141 A somewhat formal method exists by which developers commit changes
142 and push them into the "contrib" area and subsequently request that
143 the maintainer include them into "master".
144 This process is called “submitting a patch” or "submitting a change."
145 For information on submitting patches and changes, see the
146 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
147 section in the Yocto Project Development Manual.
148 </para>
149
150 <para>
151 To summarize the development workflow: a single point of entry
152 exists for changes into the project’s "master" branch of the
153 Git repository, which is controlled by the project’s maintainer.
154 And, a set of developers exist who independently develop, test, and
155 submit changes to "contrib" areas for the maintainer to examine.
156 The maintainer then chooses which changes are going to become a
157 permanent part of the project.
158 </para>
159
160 <para>
161 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
162 </para>
163
164 <para>
165 While each development environment is unique, there are some best
166 practices or methods that help development run smoothly.
167 The following list describes some of these practices.
168 For more information about Git workflows, see the workflow topics in
169 the
170 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
171 <itemizedlist>
172 <listitem><para>
173 <emphasis>Make Small Changes:</emphasis>
174 It is best to keep the changes you commit small as compared to
175 bundling many disparate changes into a single commit.
176 This practice not only keeps things manageable but also allows
177 the maintainer to more easily include or refuse changes.</para>
178
179 <para>It is also good practice to leave the repository in a
180 state that allows you to still successfully build your project.
181 In other words, do not commit half of a feature,
182 then add the other half as a separate, later commit.
183 Each commit should take you from one buildable project state
184 to another buildable state.
185 </para></listitem>
186 <listitem><para>
187 <emphasis>Use Branches Liberally:</emphasis>
188 It is very easy to create, use, and delete local branches in
189 your working Git repository.
190 You can name these branches anything you like.
191 It is helpful to give them names associated with the particular
192 feature or change on which you are working.
193 Once you are done with a feature or change and have merged it
194 into your local master branch, simply discard the temporary
195 branch.
196 </para></listitem>
197 <listitem><para>
198 <emphasis>Merge Changes:</emphasis>
199 The <filename>git merge</filename> command allows you to take
200 the changes from one branch and fold them into another branch.
201 This process is especially helpful when more than a single
202 developer might be working on different parts of the same
203 feature.
204 Merging changes also automatically identifies any collisions
205 or "conflicts" that might happen as a result of the same lines
206 of code being altered by two different developers.
207 </para></listitem>
208 <listitem><para>
209 <emphasis>Manage Branches:</emphasis>
210 Because branches are easy to use, you should use a system
211 where branches indicate varying levels of code readiness.
212 For example, you can have a "work" branch to develop in, a
213 "test" branch where the code or change is tested, a "stage"
214 branch where changes are ready to be committed, and so forth.
215 As your project develops, you can merge code across the
216 branches to reflect ever-increasing stable states of the
217 development.
218 </para></listitem>
219 <listitem><para>
220 <emphasis>Use Push and Pull:</emphasis>
221 The push-pull workflow is based on the concept of developers
222 "pushing" local commits to a remote repository, which is
223 usually a contribution repository.
224 This workflow is also based on developers "pulling" known
225 states of the project down into their local development
226 repositories.
227 The workflow easily allows you to pull changes submitted by
228 other developers from the upstream repository into your
229 work area ensuring that you have the most recent software
230 on which to develop.
231 The Yocto Project has two scripts named
232 <filename>create-pull-request</filename> and
233 <filename>send-pull-request</filename> that ship with the
234 release to facilitate this workflow.
235 You can find these scripts in the <filename>scripts</filename>
236 folder of the
237 <link linkend='source-directory'>Source Directory</link>.
238 For information on how to use these scripts, see the
239 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>"
240 section in the Yocto Project Development Manual.
241 </para></listitem>
242 <listitem><para>
243 <emphasis>Patch Workflow:</emphasis>
244 This workflow allows you to notify the maintainer through an
245 email that you have a change (or patch) you would like
246 considered for the "master" branch of the Git repository.
247 To send this type of change, you format the patch and then
248 send the email using the Git commands
249 <filename>git format-patch</filename> and
250 <filename>git send-email</filename>.
251 For information on how to use these scripts, see the
252 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
253 section in the Yocto Project Development Manual.
254 </para></listitem>
255 </itemizedlist>
256 </para>
257</section>
258
68<section id='yocto-project-repositories'> 259<section id='yocto-project-repositories'>
69 <title>Yocto Project Source Repositories</title> 260 <title>Yocto Project Source Repositories</title>
70 261