diff options
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r-- | documentation/ref-manual/figures/git-workflow.png | bin | 0 -> 26586 bytes | |||
-rw-r--r-- | documentation/ref-manual/ref-development-environment.xml | 191 |
2 files changed, 191 insertions, 0 deletions
diff --git a/documentation/ref-manual/figures/git-workflow.png b/documentation/ref-manual/figures/git-workflow.png new file mode 100644 index 0000000000..e401330a12 --- /dev/null +++ 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 | ||