GNOME.org
 

[gnome-continuous-yocto/gnomeostree-3.28-rocko: 6399/8267] dev-manual, ref-manual: Moved "Workflows" section to ref-manual

commit c7969c64bb1d8b667efc3c3abe48f9e1bec1d1f2
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Thu Jun 15 09:11:09 2017 -0700

    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>

 documentation/Makefile                             |    4 +-
 documentation/dev-manual/dev-manual-newbie.xml     |  148 ---------------
 .../figures/git-workflow.png                       |  Bin 26586 -> 26586 bytes
 .../ref-manual/ref-development-environment.xml     |  191 ++++++++++++++++++++
 4 files changed, 193 insertions(+), 150 deletions(-)
---
diff --git a/documentation/Makefile b/documentation/Makefile
index 131c0b7..6a2f22e 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -129,7 +129,7 @@ TARFILES = dev-style.css dev-manual.html \
         else
 TARFILES = dev-style.css dev-manual.html \
            figures/bsp-dev-flow.png \
-           figures/dev-title.png figures/git-workflow.png \
+           figures/dev-title.png \
            figures/kernel-dev-flow.png \
            figures/kernel-overview-1.png figures/kernel-overview-2-generic.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/sdk-generation.png figures/building-an-image.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
 FIGURES = figures
 STYLESHEET = $(DOC)/*.css
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index aca2920..c2147b3 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -617,154 +617,6 @@
     </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'>
     <title>Submitting a Defect Against the Yocto Project</title>
 
diff --git a/documentation/ref-manual/ref-development-environment.xml 
b/documentation/ref-manual/ref-development-environment.xml
index 5b0557d..08e790b 100644
--- a/documentation/ref-manual/ref-development-environment.xml
+++ b/documentation/ref-manual/ref-development-environment.xml
@@ -65,6 +65,197 @@
     </para>
 </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'>
     <title>Yocto Project Source Repositories</title>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]