diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2017-06-15 09:11:09 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-06-22 09:16:43 +0100 |
commit | c7969c64bb1d8b667efc3c3abe48f9e1bec1d1f2 (patch) | |
tree | 66f510cf2d98def9f5858f3004b0a5e1d42af186 /documentation/dev-manual/dev-manual-newbie.xml | |
parent | d17632463e2d54c91ef9b334c14e5067b8171b4b (diff) | |
download | poky-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/dev-manual/dev-manual-newbie.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 148 |
1 files changed, 0 insertions, 148 deletions
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 | ||