diff options
Diffstat (limited to 'documentation/getting-started/eclipse/html/getting-started/workflows.html')
| -rw-r--r-- | documentation/getting-started/eclipse/html/getting-started/workflows.html | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/documentation/getting-started/eclipse/html/getting-started/workflows.html b/documentation/getting-started/eclipse/html/getting-started/workflows.html new file mode 100644 index 0000000000..9d53975678 --- /dev/null +++ b/documentation/getting-started/eclipse/html/getting-started/workflows.html | |||
| @@ -0,0 +1,207 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | ||
| 4 | <title>2.3. Workflows</title> | ||
| 5 | <link rel="stylesheet" type="text/css" href="../book.css"> | ||
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> | ||
| 7 | <link rel="home" href="index.html" title="Getting Started With Yocto Project"> | ||
| 8 | <link rel="up" href="overview-development-environment.html" title="Chapter 2. The Yocto Project Development Environment"> | ||
| 9 | <link rel="prev" href="open-source-philosophy.html" title="2.2. Open Source Philosophy"> | ||
| 10 | <link rel="next" href="git.html" title="2.4. Git"> | ||
| 11 | </head> | ||
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3. Workflows"> | ||
| 13 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | ||
| 14 | <a name="workflows"></a>2.3. Workflows</h2></div></div></div> | ||
| 15 | <p> | ||
| 16 | This section provides workflow concepts using the Yocto Project and | ||
| 17 | Git. | ||
| 18 | In particular, the information covers basic practices that describe | ||
| 19 | roles and actions in a collaborative development environment. | ||
| 20 | </p> | ||
| 21 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 22 | <h3 class="title">Note</h3> | ||
| 23 | If you are familiar with this type of development environment, you | ||
| 24 | might not want to read this section. | ||
| 25 | </div> | ||
| 26 | <p> | ||
| 27 | </p> | ||
| 28 | <p> | ||
| 29 | The Yocto Project files are maintained using Git in "master" | ||
| 30 | branches whose Git histories track every change and whose structures | ||
| 31 | provides branches for all diverging functionality. | ||
| 32 | Although there is no need to use Git, many open source projects do so. | ||
| 33 | </p> | ||
| 34 | <p> | ||
| 35 | |||
| 36 | </p> | ||
| 37 | <p> | ||
| 38 | For the Yocto Project, a key individual called the "maintainer" is | ||
| 39 | responsible for the "master" branch of a given Git repository. | ||
| 40 | The "master" branch is the “upstream” repository from which final or | ||
| 41 | most recent builds of the project occur. | ||
| 42 | The maintainer is responsible for accepting changes from other | ||
| 43 | developers and for organizing the underlying branch structure to | ||
| 44 | reflect release strategies and so forth. | ||
| 45 | </p> | ||
| 46 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> | ||
| 47 | <h3 class="title">Note</h3>For information on finding out who is responsible for (maintains) | ||
| 48 | a particular area of code, see the | ||
| 49 | "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">Submitting a Change to the Yocto Project</a>" | ||
| 50 | section of the Yocto Project Development Tasks Manual. | ||
| 51 | </div> | ||
| 52 | <p> | ||
| 53 | </p> | ||
| 54 | <p> | ||
| 55 | The Yocto Project <code class="filename">poky</code> Git repository also has an | ||
| 56 | upstream contribution Git repository named | ||
| 57 | <code class="filename">poky-contrib</code>. | ||
| 58 | You can see all the branches in this repository using the web interface | ||
| 59 | of the | ||
| 60 | <a class="ulink" href="http://git.yoctoproject.org" target="_self">Source Repositories</a> organized | ||
| 61 | within the "Poky Support" area. | ||
| 62 | These branches temporarily hold changes to the project that have been | ||
| 63 | submitted or committed by the Yocto Project development team and by | ||
| 64 | community members who contribute to the project. | ||
| 65 | The maintainer determines if the changes are qualified to be moved | ||
| 66 | from the "contrib" branches into the "master" branch of the Git | ||
| 67 | repository. | ||
| 68 | </p> | ||
| 69 | <p> | ||
| 70 | Developers (including contributing community members) create and | ||
| 71 | maintain cloned repositories of the upstream "master" branch. | ||
| 72 | The cloned repositories are local to their development platforms and | ||
| 73 | are used to develop changes. | ||
| 74 | When a developer is satisfied with a particular feature or change, | ||
| 75 | they "push" the changes to the appropriate "contrib" repository. | ||
| 76 | </p> | ||
| 77 | <p> | ||
| 78 | Developers are responsible for keeping their local repository | ||
| 79 | up-to-date with "master". | ||
| 80 | They are also responsible for straightening out any conflicts that | ||
| 81 | might arise within files that are being worked on simultaneously by | ||
| 82 | more than one person. | ||
| 83 | All this work is done locally on the developer’s machine before | ||
| 84 | anything is pushed to a "contrib" area and examined at the maintainer’s | ||
| 85 | level. | ||
| 86 | </p> | ||
| 87 | <p> | ||
| 88 | A somewhat formal method exists by which developers commit changes | ||
| 89 | and push them into the "contrib" area and subsequently request that | ||
| 90 | the maintainer include them into "master". | ||
| 91 | This process is called “submitting a patch” or "submitting a change." | ||
| 92 | For information on submitting patches and changes, see the | ||
| 93 | "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">Submitting a Change to the Yocto Project</a>" | ||
| 94 | section in the Yocto Project Development Tasks Manual. | ||
| 95 | </p> | ||
| 96 | <p> | ||
| 97 | To summarize the development workflow: a single point of entry | ||
| 98 | exists for changes into the project’s "master" branch of the | ||
| 99 | Git repository, which is controlled by the project’s maintainer. | ||
| 100 | And, a set of developers exist who independently develop, test, and | ||
| 101 | submit changes to "contrib" areas for the maintainer to examine. | ||
| 102 | The maintainer then chooses which changes are going to become a | ||
| 103 | permanent part of the project. | ||
| 104 | </p> | ||
| 105 | <p> | ||
| 106 | </p> | ||
| 107 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 270px"><td align="left"><img src="figures/git-workflow.png" align="left" height="270"></td></tr></table> | ||
| 108 | <p> | ||
| 109 | </p> | ||
| 110 | <p> | ||
| 111 | While each development environment is unique, there are some best | ||
| 112 | practices or methods that help development run smoothly. | ||
| 113 | The following list describes some of these practices. | ||
| 114 | For more information about Git workflows, see the workflow topics in | ||
| 115 | the | ||
| 116 | <a class="ulink" href="http://book.git-scm.com" target="_self">Git Community Book</a>. | ||
| 117 | </p> | ||
| 118 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | ||
| 119 | <li class="listitem"> | ||
| 120 | <p> | ||
| 121 | <span class="emphasis"><em>Make Small Changes:</em></span> | ||
| 122 | It is best to keep the changes you commit small as compared to | ||
| 123 | bundling many disparate changes into a single commit. | ||
| 124 | This practice not only keeps things manageable but also allows | ||
| 125 | the maintainer to more easily include or refuse changes.</p> | ||
| 126 | <p>It is also good practice to leave the repository in a | ||
| 127 | state that allows you to still successfully build your project. | ||
| 128 | In other words, do not commit half of a feature, | ||
| 129 | then add the other half as a separate, later commit. | ||
| 130 | Each commit should take you from one buildable project state | ||
| 131 | to another buildable state. | ||
| 132 | </p> | ||
| 133 | </li> | ||
| 134 | <li class="listitem"><p> | ||
| 135 | <span class="emphasis"><em>Use Branches Liberally:</em></span> | ||
| 136 | It is very easy to create, use, and delete local branches in | ||
| 137 | your working Git repository. | ||
| 138 | You can name these branches anything you like. | ||
| 139 | It is helpful to give them names associated with the particular | ||
| 140 | feature or change on which you are working. | ||
| 141 | Once you are done with a feature or change and have merged it | ||
| 142 | into your local master branch, simply discard the temporary | ||
| 143 | branch. | ||
| 144 | </p></li> | ||
| 145 | <li class="listitem"><p> | ||
| 146 | <span class="emphasis"><em>Merge Changes:</em></span> | ||
| 147 | The <code class="filename">git merge</code> command allows you to take | ||
| 148 | the changes from one branch and fold them into another branch. | ||
| 149 | This process is especially helpful when more than a single | ||
| 150 | developer might be working on different parts of the same | ||
| 151 | feature. | ||
| 152 | Merging changes also automatically identifies any collisions | ||
| 153 | or "conflicts" that might happen as a result of the same lines | ||
| 154 | of code being altered by two different developers. | ||
| 155 | </p></li> | ||
| 156 | <li class="listitem"><p> | ||
| 157 | <span class="emphasis"><em>Manage Branches:</em></span> | ||
| 158 | Because branches are easy to use, you should use a system | ||
| 159 | where branches indicate varying levels of code readiness. | ||
| 160 | For example, you can have a "work" branch to develop in, a | ||
| 161 | "test" branch where the code or change is tested, a "stage" | ||
| 162 | branch where changes are ready to be committed, and so forth. | ||
| 163 | As your project develops, you can merge code across the | ||
| 164 | branches to reflect ever-increasing stable states of the | ||
| 165 | development. | ||
| 166 | </p></li> | ||
| 167 | <li class="listitem"><p> | ||
| 168 | <span class="emphasis"><em>Use Push and Pull:</em></span> | ||
| 169 | The push-pull workflow is based on the concept of developers | ||
| 170 | "pushing" local commits to a remote repository, which is | ||
| 171 | usually a contribution repository. | ||
| 172 | This workflow is also based on developers "pulling" known | ||
| 173 | states of the project down into their local development | ||
| 174 | repositories. | ||
| 175 | The workflow easily allows you to pull changes submitted by | ||
| 176 | other developers from the upstream repository into your | ||
| 177 | work area ensuring that you have the most recent software | ||
| 178 | on which to develop. | ||
| 179 | The Yocto Project has two scripts named | ||
| 180 | <code class="filename">create-pull-request</code> and | ||
| 181 | <code class="filename">send-pull-request</code> that ship with the | ||
| 182 | release to facilitate this workflow. | ||
| 183 | You can find these scripts in the <code class="filename">scripts</code> | ||
| 184 | folder of the | ||
| 185 | <a class="link" href="../ref-manual/source-directory.html" target="_self">Source Directory</a>. | ||
| 186 | For information on how to use these scripts, see the | ||
| 187 | "<a class="link" href="../dev-manual/pushing-a-change-upstream.html" target="_self">Using Scripts to Push a Change Upstream and Request a Pull</a>" | ||
| 188 | section in the Yocto Project Development Tasks Manual. | ||
| 189 | </p></li> | ||
| 190 | <li class="listitem"><p> | ||
| 191 | <span class="emphasis"><em>Patch Workflow:</em></span> | ||
| 192 | This workflow allows you to notify the maintainer through an | ||
| 193 | email that you have a change (or patch) you would like | ||
| 194 | considered for the "master" branch of the Git repository. | ||
| 195 | To send this type of change, you format the patch and then | ||
| 196 | send the email using the Git commands | ||
| 197 | <code class="filename">git format-patch</code> and | ||
| 198 | <code class="filename">git send-email</code>. | ||
| 199 | For information on how to use these scripts, see the | ||
| 200 | "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">Submitting a Change to the Yocto Project</a>" | ||
| 201 | section in the Yocto Project Development Tasks Manual. | ||
| 202 | </p></li> | ||
| 203 | </ul></div> | ||
| 204 | <p> | ||
| 205 | </p> | ||
| 206 | </div></body> | ||
| 207 | </html> | ||