summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/getting-started/getting-started-development-environment.xml44
1 files changed, 26 insertions, 18 deletions
diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml
index f7d646c2b7..0c08859ea0 100644
--- a/documentation/getting-started/getting-started-development-environment.xml
+++ b/documentation/getting-started/getting-started-development-environment.xml
@@ -317,6 +317,10 @@
317 <title>Git Workflows and the Yocto Project</title> 317 <title>Git Workflows and the Yocto Project</title>
318 318
319 <para> 319 <para>
320 Developing using the Yocto Project likely requires the use of
321 <link linkend='git'>Git</link>.
322 Git is a free, open source distributed version control system
323 used as part of many collaborative design environments.
320 This section provides workflow concepts using the Yocto Project and 324 This section provides workflow concepts using the Yocto Project and
321 Git. 325 Git.
322 In particular, the information covers basic practices that describe 326 In particular, the information covers basic practices that describe
@@ -328,22 +332,24 @@
328 </para> 332 </para>
329 333
330 <para> 334 <para>
331 The Yocto Project files are maintained using Git in "master" 335 The Yocto Project files are maintained using Git in "branches"
332 branches whose Git histories track every change and whose structures 336 whose Git histories track every change and whose structures
333 provides branches for all diverging functionality. 337 provide branches for all diverging functionality.
334 Although there is no need to use Git, many open source projects do so. 338 Although there is no need to use Git, many open source projects do so.
335 <para> 339 <para>
336 340
337 </para> 341 </para>
338 For the Yocto Project, a key individual called the "maintainer" is 342 For the Yocto Project, a key individual called the "maintainer" is
339 responsible for the "master" branch of a given Git repository. 343 responsible for the integrity of the "master" branch of a given Git
344 repository.
340 The "master" branch is the “upstream” repository from which final or 345 The "master" branch is the “upstream” repository from which final or
341 most recent builds of the project occur. 346 most recent builds of a project occur.
342 The maintainer is responsible for accepting changes from other 347 The maintainer is responsible for accepting changes from other
343 developers and for organizing the underlying branch structure to 348 developers and for organizing the underlying branch structure to
344 reflect release strategies and so forth. 349 reflect release strategies and so forth.
345 <note>For information on finding out who is responsible for (maintains) 350 <note>
346 a particular area of code, see the 351 For information on finding out who is responsible for (maintains)
352 a particular area of code in the Yocto Project, see the
347 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" 353 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
348 section of the Yocto Project Development Tasks Manual. 354 section of the Yocto Project Development Tasks Manual.
349 </note> 355 </note>
@@ -357,7 +363,7 @@
357 of the 363 of the
358 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized 364 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
359 within the "Poky Support" area. 365 within the "Poky Support" area.
360 These branches temporarily hold changes to the project that have been 366 These branches hold changes (commits) to the project that have been
361 submitted or committed by the Yocto Project development team and by 367 submitted or committed by the Yocto Project development team and by
362 community members who contribute to the project. 368 community members who contribute to the project.
363 The maintainer determines if the changes are qualified to be moved 369 The maintainer determines if the changes are qualified to be moved
@@ -367,20 +373,20 @@
367 373
368 <para> 374 <para>
369 Developers (including contributing community members) create and 375 Developers (including contributing community members) create and
370 maintain cloned repositories of the upstream "master" branch. 376 maintain cloned repositories of upstream branches.
371 The cloned repositories are local to their development platforms and 377 The cloned repositories are local to their development platforms and
372 are used to develop changes. 378 are used to develop changes.
373 When a developer is satisfied with a particular feature or change, 379 When a developer is satisfied with a particular feature or change,
374 they "push" the changes to the appropriate "contrib" repository. 380 they "push" the change to the appropriate "contrib" repository.
375 </para> 381 </para>
376 382
377 <para> 383 <para>
378 Developers are responsible for keeping their local repository 384 Developers are responsible for keeping their local repository
379 up-to-date with "master". 385 up-to-date with whatever upstream branch they are working against.
380 They are also responsible for straightening out any conflicts that 386 They are also responsible for straightening out any conflicts that
381 might arise within files that are being worked on simultaneously by 387 might arise within files that are being worked on simultaneously by
382 more than one person. 388 more than one person.
383 All this work is done locally on the developer’s machine before 389 All this work is done locally on the development host before
384 anything is pushed to a "contrib" area and examined at the maintainer’s 390 anything is pushed to a "contrib" area and examined at the maintainer’s
385 level. 391 level.
386 </para> 392 </para>
@@ -388,7 +394,7 @@
388 <para> 394 <para>
389 A somewhat formal method exists by which developers commit changes 395 A somewhat formal method exists by which developers commit changes
390 and push them into the "contrib" area and subsequently request that 396 and push them into the "contrib" area and subsequently request that
391 the maintainer include them into "master". 397 the maintainer include them into an upstream branch.
392 This process is called “submitting a patch” or "submitting a change." 398 This process is called “submitting a patch” or "submitting a change."
393 For information on submitting patches and changes, see the 399 For information on submitting patches and changes, see the
394 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" 400 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
@@ -397,7 +403,7 @@
397 403
398 <para> 404 <para>
399 To summarize the development workflow: a single point of entry 405 To summarize the development workflow: a single point of entry
400 exists for changes into the project’s "master" branch of the 406 exists for changes into a "master" or development branch of the
401 Git repository, which is controlled by the project’s maintainer. 407 Git repository, which is controlled by the project’s maintainer.
402 And, a set of developers exist who independently develop, test, and 408 And, a set of developers exist who independently develop, test, and
403 submit changes to "contrib" areas for the maintainer to examine. 409 submit changes to "contrib" areas for the maintainer to examine.
@@ -422,9 +428,11 @@
422 It is best to keep the changes you commit small as compared to 428 It is best to keep the changes you commit small as compared to
423 bundling many disparate changes into a single commit. 429 bundling many disparate changes into a single commit.
424 This practice not only keeps things manageable but also allows 430 This practice not only keeps things manageable but also allows
425 the maintainer to more easily include or refuse changes.</para> 431 the maintainer to more easily include or refuse changes.
426 432 </para></listitem>
427 <para>It is also good practice to leave the repository in a 433 <listitem><para>
434 <emphasis>Make Complete Changes:</emphasis>
435 It is also good practice to leave the repository in a
428 state that allows you to still successfully build your project. 436 state that allows you to still successfully build your project.
429 In other words, do not commit half of a feature, 437 In other words, do not commit half of a feature,
430 then add the other half as a separate, later commit. 438 then add the other half as a separate, later commit.
@@ -434,7 +442,7 @@
434 <listitem><para> 442 <listitem><para>
435 <emphasis>Use Branches Liberally:</emphasis> 443 <emphasis>Use Branches Liberally:</emphasis>
436 It is very easy to create, use, and delete local branches in 444 It is very easy to create, use, and delete local branches in
437 your working Git repository. 445 your working Git repository on the development host.
438 You can name these branches anything you like. 446 You can name these branches anything you like.
439 It is helpful to give them names associated with the particular 447 It is helpful to give them names associated with the particular
440 feature or change on which you are working. 448 feature or change on which you are working.