summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-20 06:37:18 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-06-22 09:16:44 +0100
commitcd9279ab5cb572d804806283c13857346dc54de8 (patch)
tree814aa7fa9e03d31e3f2d7be71a10af4e3bf3fdd4 /documentation/dev-manual
parente928b5251cdc7baba8a78380041b8156c106f9fc (diff)
downloadpoky-cd9279ab5cb572d804806283c13857346dc54de8.tar.gz
dev-manual: Updated the section on the YP development environment
Fixes [YOCTO #11630] Extensively updated the development environment section by creating a task-oriented section. (From yocto-docs rev: d440f0b5ceb1aca57a73d8bced515ae0bd3188f7) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml631
1 files changed, 322 insertions, 309 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 1bb82b711d..1d9926c6cd 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -7,12 +7,12 @@
7<title>The Yocto Project Open Source Development Environment</title> 7<title>The Yocto Project Open Source Development Environment</title>
8 8
9<section id="usingpoky-changes-collaborate"> 9<section id="usingpoky-changes-collaborate">
10 <title>Using the Yocto Project in a Team Environment</title> 10 <title>Setting Up a Team Yocto Project Development Environment</title>
11 11
12 <para> 12 <para>
13 It might not be immediately clear how you can use the Yocto 13 It might not be immediately clear how you can use the Yocto
14 Project in a team environment, or scale it for a large team of 14 Project in a team development environment, or scale it for a large
15 developers. 15 team of developers.
16 One of the strengths of the Yocto Project is that it is extremely 16 One of the strengths of the Yocto Project is that it is extremely
17 flexible. 17 flexible.
18 Thus, you can adapt it to many different use cases and scenarios. 18 Thus, you can adapt it to many different use cases and scenarios.
@@ -21,337 +21,350 @@
21 </para> 21 </para>
22 22
23 <para> 23 <para>
24 To help with these types of situations, this section presents 24 To help you understand how to set up this type of environment,
25 some of the project's most successful experiences, 25 this section presents a procedure that gives you the information
26 practices, solutions, and available technologies that work well. 26 to learn how to get the results you want.
27 Keep in mind, the information here is a starting point. 27 The procedure is high-level and presents some of the project's most
28 successful experiences, practices, solutions, and available
29 technologies that work well.
30 Keep in mind, the procedure here is a starting point.
28 You can build off it and customize it to fit any 31 You can build off it and customize it to fit any
29 particular working environment and set of practices. 32 particular working environment and set of practices.
30 </para> 33 <orderedlist>
31 34 <listitem><para>
32 <section id='best-practices-system-configurations'> 35 <emphasis>Determine Who is Going to be Developing:</emphasis>
33 <title>System Configurations</title> 36 You need to understand who is going to be doing anything
34 37 related to the Yocto Project and what their roles would be.
35 <para> 38 Making this determination is essential to completing the
36 Systems across a large team should meet the needs of 39 steps two and three, which are to get your equipment together
37 two types of developers: those working on the contents of the 40 and set up your development environment's hardware topology.
38 operating system image itself and those developing applications. 41 </para>
39 Regardless of the type of developer, their workstations must 42
40 be both reasonably powerful and run Linux. 43 <para>The following roles exist:
41 </para> 44 <itemizedlist>
45 <listitem><para>
46 <emphasis>Application Development:</emphasis>
47 These types of developers do application level work
48 on top of an existing software stack.
49 </para></listitem>
50 <listitem><para>
51 <emphasis>Core System Development:</emphasis>
52 These types of developers work on the contents of the
53 operating system image itself.
54 </para></listitem>
55 <listitem><para>
56 <emphasis>Build Engineer:</emphasis>
57 This type of developer manages Autobuilders and
58 releases.
59 Not all environments need a Build Engineer.
60 </para></listitem>
61 <listitem><para>
62 <emphasis>Test Engineer:</emphasis>
63 This type of developer creates and manages automated
64 tests needed to ensure all application and core
65 system development meets desired quality standards.
66 </para></listitem>
67 </itemizedlist>
68 </para></listitem>
69 <listitem><para>
70 <emphasis>Gather the Hardware:</emphasis>
71 Based on the size and make-up of the team, get the hardware
72 together.
73 Any development, build, or test engineer should be using
74 a system that is running a supported Linux distribution.
75 Systems, in general, should be high performance (e.g. dual,
76 six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
77 You can help ensure efficiency by having any machines used
78 for testing or that run Autobuilders be as high performance
79 as possible.
80 </para></listitem>
81 <listitem><para>
82 <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
83 Now that you know how many developers and support engineers
84 are required, you can understand the topology of the
85 hardware environment.
86 The following figure shows a moderately sized Yocto Project
87 development environment.
42 88
43 <section id='best-practices-application-development'> 89 <para role="writernotes">
44 <title>Application Development</title> 90 Need figure.</para>
45 91
46 <para> 92 </para></listitem>
47 For developers who mainly do application level work 93 <listitem><para>
48 on top of an existing software stack, 94 <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
49 the following list shows practices that work best. 95 Keeping your
50 For information on using a Software Development Kit (SDK), see 96 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
51 the 97 and any software you are developing under the
52 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>: 98 control of an SCM system that is compatible
99 with the OpenEmbedded build system is advisable.
100 Of the SCMs BitBake supports, the
101 Yocto Project team strongly recommends using
102 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>.
103 Git is a distributed system that is easy to backup,
104 allows you to work remotely, and then connects back to the
105 infrastructure.
106 <note>
107 For information about BitBake, see the
108 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
109 </note></para>
110
111 <para>It is relatively easy to set up Git services and create
112 infrastructure like
113 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
114 which is based on server software called
115 <filename>gitolite</filename> with <filename>cgit</filename>
116 being used to generate the web interface that lets you view the
117 repositories.
118 The <filename>gitolite</filename> software identifies users
119 using SSH keys and allows branch-based
120 access controls to repositories that you can control as little
121 or as much as necessary.
122
123 <note>
124 The setup of these services is beyond the scope of this
125 manual.
126 However, sites such as these exist that describe how to
127 perform setup:
128 <itemizedlist>
129 <listitem><para>
130 <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
131 Describes how to install <filename>gitolite</filename>
132 on the server.
133 </para></listitem>
134 <listitem><para>
135 <ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
136 All topics for <filename>gitolite</filename>.
137 </para></listitem>
138 <listitem><para>
139 <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
140 Documentation on how to create interfaces and frontends
141 for Git.
142 </para></listitem>
143 </itemizedlist>
144 </note>
145 </para></listitem>
146 <listitem><para>
147 <emphasis>Set up the Application Development Machines:</emphasis>
148 As mentioned earlier, application developers are creating
149 applications on top of existing software stacks.
150 Following are some best practices for setting up machines
151 that do application development:
53 <itemizedlist> 152 <itemizedlist>
54 <listitem><para>Use a pre-built toolchain that 153 <listitem><para>
154 Use a pre-built toolchain that
55 contains the software stack itself. 155 contains the software stack itself.
56 Then, develop the application code on top of the 156 Then, develop the application code on top of the
57 stack. 157 stack.
58 This method works well for small numbers of relatively 158 This method works well for small numbers of relatively
59 isolated applications.</para></listitem> 159 isolated applications.
60 <listitem><para>When possible, use the Yocto Project 160 </para></listitem>
61 plug-in for the <trademark class='trade'>Eclipse</trademark> IDE 161 <listitem><para>
162 When possible, use the Yocto Project
163 plug-in for the
164 <trademark class='trade'>Eclipse</trademark> IDE
62 and SDK development practices. 165 and SDK development practices.
63 For more information, see the 166 For more information, see the
64 "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>". 167 "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>".
65 </para></listitem> 168 </para></listitem>
66 <listitem><para>Keep your cross-development toolchains 169 <listitem><para>
67 updated. 170 Keep your cross-development toolchains updated.
68 You can do this through provisioning either as new 171 You can do this through provisioning either as new
69 toolchain downloads or as updates through a package 172 toolchain downloads or as updates through a package
70 update mechanism using <filename>opkg</filename> 173 update mechanism using <filename>opkg</filename>
71 to provide updates to an existing toolchain. 174 to provide updates to an existing toolchain.
72 The exact mechanics of how and when to do this are a 175 The exact mechanics of how and when to do this are a
73 question for local policy.</para></listitem> 176 question for local policy.
74 <listitem><para>Use multiple toolchains installed locally 177 </para></listitem>
178 <listitem><para>
179 Use multiple toolchains installed locally
75 into different locations to allow development across 180 into different locations to allow development across
76 versions.</para></listitem> 181 versions.
182 </para></listitem>
77 </itemizedlist> 183 </itemizedlist>
78 </para> 184 </para></listitem>
79 </section> 185 <listitem><para>
80 186 <emphasis>Set up the Core Development Machines:</emphasis>
81 <section id='best-practices-core-system-development'> 187 As mentioned earlier, these types of developers work on the
82 <title>Core System Development</title> 188 contents of the operating system itself.
83 189 Following are some best practices for setting up machines
84 <para> 190 used for developing images:
85 For core system development, it is often best to have the
86 build system itself available on the developer workstations
87 so developers can run their own builds and directly
88 rebuild the software stack.
89 You should keep the core system unchanged as much as
90 possible and do your work in layers on top of the core system.
91 Doing so gives you a greater level of portability when
92 upgrading to new versions of the core system or Board
93 Support Packages (BSPs).
94 You can share layers amongst the developers of a particular
95 project and contain the policy configuration that defines
96 the project.
97 </para>
98
99 <para>
100 Aside from the previous best practices, there exists a number
101 of tips and tricks that can help speed up core development
102 projects:
103 <itemizedlist> 191 <itemizedlist>
104 <listitem><para>Use a 192 <listitem><para>
105 <ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink> 193 Have the Yocto Project build system itself available on
106 (sstate) among groups of developers who are on a 194 the developer workstations so developers can run their own
107 fast network. 195 builds and directly rebuild the software stack.
108 The best way to share sstate is through a
109 Network File System (NFS) share.
110 The first user to build a given component for the
111 first time contributes that object to the sstate,
112 while subsequent builds from other developers then
113 reuse the object rather than rebuild it themselves.
114 </para>
115 <para>Although it is possible to use other protocols for the
116 sstate such as HTTP and FTP, you should avoid these.
117 Using HTTP limits the sstate to read-only and
118 FTP provides poor performance.
119 </para></listitem> 196 </para></listitem>
120 <listitem><para>Have autobuilders contribute to the sstate 197 <listitem><para>
121 pool similarly to how the developer workstations 198 Keep the core system unchanged as much as
122 contribute. 199 possible and do your work in layers on top of the
123 For information, see the 200 core system.
124 "<link linkend='best-practices-autobuilders'>Autobuilders</link>" 201 Doing so gives you a greater level of portability when
125 section.</para></listitem> 202 upgrading to new versions of the core system or Board
126 <listitem><para>Build stand-alone tarballs that contain 203 Support Packages (BSPs).
127 "missing" system requirements if for some reason
128 developer workstations do not meet minimum system
129 requirements such as latest Python versions,
130 <filename>chrpath</filename>, or other tools.
131 You can install and relocate the tarball exactly as you
132 would the usual cross-development toolchain so that
133 all developers can meet minimum version requirements
134 on most distributions.</para></listitem>
135 <listitem><para>Use a small number of shared,
136 high performance systems for testing purposes
137 (e.g. dual, six-core Xeons with 24 Gbytes of RAM
138 and plenty of disk space).
139 Developers can use these systems for wider, more
140 extensive testing while they continue to develop
141 locally using their primary development system.
142 </para></listitem> 204 </para></listitem>
143 <listitem><para>Enable the PR Service when package feeds 205 <listitem><para>
144 need to be incremental with continually increasing 206 Share layers amongst the developers of a
145 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink> 207 particular project and contain the policy configuration
146 values. 208 that defines the project.
147 Typically, this situation occurs when you use or
148 publish package feeds and use a shared state.
149 You should enable the PR Service for all users who
150 use the shared state pool.
151 For more information on the PR Service, see the
152 "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>".
153 </para></listitem> 209 </para></listitem>
154 </itemizedlist> 210 </itemizedlist>
155 </para> 211 </para></listitem>
156 </section> 212 <listitem><para>
157 </section> 213 <emphasis>Set up an Autobuilder:</emphasis>
158 214 Autobuilders are often the core of the development
159 <section id='best-practices-source-control-management'> 215 environment.
160 <title>Source Control Management (SCM)</title> 216 It is here that changes from individual developers are brought
161 217 together and centrally tested and subsequent decisions about
162 <para> 218 releases can be made.
163 Keeping your 219 Autobuilders also allow for "continuous integration" style
164 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> 220 testing of software components and regression identification
165 and any software you are developing under the 221 and tracking.</para>
166 control of an SCM system that is compatible 222
167 with the OpenEmbedded build system is advisable. 223 <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
168 Of the SCMs BitBake supports, the 224 for more information and links to buildbot.
169 Yocto Project team strongly recommends using 225 The Yocto Project team has found this implementation
170 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>. 226 works well in this role.
171 Git is a distributed system that is easy to backup, 227 A public example of this is the Yocto Project
172 allows you to work remotely, and then connects back to the 228 Autobuilders, which we use to test the overall health of the
173 infrastructure. 229 project.</para>
174 <note> 230
175 For information about BitBake, see the 231 <para>The features of this system are:
176 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. 232 <itemizedlist>
177 </note> 233 <listitem><para>
178 </para> 234 Highlights when commits break the build.
179 235 </para></listitem>
180 <para> 236 <listitem><para>
181 It is relatively easy to set up Git services and create 237 Populates an sstate cache from which
182 infrastructure like 238 developers can pull rather than requiring local
183 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>, 239 builds.
184 which is based on server software called 240 </para></listitem>
185 <filename>gitolite</filename> with <filename>cgit</filename> 241 <listitem><para>
186 being used to generate the web interface that lets you view the 242 Allows commit hook triggers,
187 repositories. 243 which trigger builds when commits are made.
188 The <filename>gitolite</filename> software identifies users 244 </para></listitem>
189 using SSH keys and allows branch-based 245 <listitem><para>
190 access controls to repositories that you can control as little 246 Allows triggering of automated image booting
191 or as much as necessary. 247 and testing under the QuickEMUlator (QEMU).
192 </para> 248 </para></listitem>
193 249 <listitem><para>
194 <note> 250 Supports incremental build testing and
195 The setup of these services is beyond the scope of this manual. 251 from-scratch builds.
196 However, sites such as these exist that describe how to perform 252 </para></listitem>
197 setup: 253 <listitem><para>
198 <itemizedlist> 254 Shares output that allows developer
199 <listitem><para><ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>: 255 testing and historical regression investigation.
200 Describes how to install <filename>gitolite</filename> 256 </para></listitem>
201 on the server.</para></listitem> 257 <listitem><para>
202 <listitem><para><ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>: 258 Creates output that can be used for releases.
203 All topics for <filename>gitolite</filename>. 259 </para></listitem>
204 </para></listitem> 260 <listitem><para>
205 <listitem><para><ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>: 261 Allows scheduling of builds so that resources
206 Documentation on how to create interfaces and frontends 262 can be used efficiently.
207 for Git.</para></listitem> 263 </para></listitem>
208 </itemizedlist> 264 </itemizedlist>
209 </note> 265 </para></listitem>
210 </section> 266 <listitem><para>
211 267 <emphasis>Set up Test Machines:</emphasis>
212 <section id='best-practices-autobuilders'> 268 Use a small number of shared, high performance systems
213 <title>Autobuilders</title> 269 for testing purposes.
214 270 Developers can use these systems for wider, more
215 <para> 271 extensive testing while they continue to develop
216 Autobuilders are often the core of a development project. 272 locally using their primary development system.
217 It is here that changes from individual developers are brought 273 </para></listitem>
218 together and centrally tested and subsequent decisions about 274 <listitem><para>
219 releases can be made. 275 <emphasis>Document Policies and Change Flow:</emphasis>
220 Autobuilders also allow for "continuous integration" style 276 The Yocto Project itself uses a hierarchical structure and a
221 testing of software components and regression identification 277 pull model.
222 and tracking. 278 Scripts exist to create and send pull requests
223 </para> 279 (i.e. <filename>create-pull-request</filename> and
224 280 <filename>send-pull-request</filename>).
225 <para> 281 This model is in line with other open source projects where
226 See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>" 282 maintainers are responsible for specific areas of the project
227 for more information and links to buildbot. 283 and a single maintainer handles the final "top-of-tree" merges.
228 The Yocto Project team has found this implementation 284 <note>
229 works well in this role. 285 You can also use a more collective push model.
230 A public example of this is the Yocto Project 286 The <filename>gitolite</filename> software supports both the
231 Autobuilders, which we use to test the overall health of the 287 push and pull models quite easily.
232 project. 288 </note></para>
233 </para> 289
234 290 <para>As with any development environment, it is important
235 <para> 291 to document the policy used as well as any main project
236 The features of this system are: 292 guidelines so they are understood by everyone.
237 <itemizedlist> 293 It is also a good idea to have well structured
238 <listitem><para>Highlights when commits break the build. 294 commit messages, which are usually a part of a project's
239 </para></listitem> 295 guidelines.
240 <listitem><para>Populates an sstate cache from which 296 Good commit messages are essential when looking back in time and
241 developers can pull rather than requiring local 297 trying to understand why changes were made.</para>
242 builds.</para></listitem> 298
243 <listitem><para>Allows commit hook triggers, 299 <para>If you discover that changes are needed to the core
244 which trigger builds when commits are made. 300 layer of the project, it is worth sharing those with the
245 </para></listitem> 301 community as soon as possible.
246 <listitem><para>Allows triggering of automated image booting 302 Chances are if you have discovered the need for changes,
247 and testing under the QuickEMUlator (QEMU). 303 someone else in the community needs them also.
248 </para></listitem> 304 </para></listitem>
249 <listitem><para>Supports incremental build testing and 305 <listitem><para>
250 from-scratch builds.</para></listitem> 306 <emphasis>Development Environment Summary:</emphasis>
251 <listitem><para>Shares output that allows developer 307 Aside from the previous steps, some best practices exist
252 testing and historical regression investigation. 308 within the Yocto Project development environment.
253 </para></listitem> 309 Consider the following:
254 <listitem><para>Creates output that can be used for releases. 310 <itemizedlist>
255 </para></listitem> 311 <listitem><para>
256 <listitem><para>Allows scheduling of builds so that resources 312 Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>
257 can be used efficiently.</para></listitem> 313 as the source control system.
258 </itemizedlist> 314 </para></listitem>
259 </para> 315 <listitem><para>
260 </section> 316 Maintain your Metadata in layers that make sense
261 317 for your situation.
262 <section id='best-practices-policies-and-change-flow'> 318 See the "<link linkend='understanding-and-creating-layers'>Understanding
263 <title>Policies and Change Flow</title> 319 and Creating Layers</link>" section for more information on
264 320 layers.
265 <para> 321 </para></listitem>
266 The Yocto Project itself uses a hierarchical structure and a 322 <listitem><para>
267 pull model. 323 Separate the project's Metadata and code by using
268 Scripts exist to create and send pull requests 324 separate Git repositories.
269 (i.e. <filename>create-pull-request</filename> and 325 See the
270 <filename>send-pull-request</filename>). 326 "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
271 This model is in line with other open source projects where 327 section for information on these repositories.
272 maintainers are responsible for specific areas of the project 328 See the
273 and a single maintainer handles the final "top-of-tree" merges. 329 "<link linkend='getting-setup'>Getting Set Up</link>"
274 </para> 330 section for information on how to set up local Git
275 331 repositories for related upstream Yocto Project
276 <note> 332 Git repositories.
277 You can also use a more collective push model. 333 </para></listitem>
278 The <filename>gitolite</filename> software supports both the 334 <listitem><para>
279 push and pull models quite easily. 335 Set up the directory for the shared state cache
280 </note> 336 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
281 337 where it makes sense.
282 <para> 338 For example, set up the sstate cache on a system used
283 As with any development environment, it is important 339 by developers in the same organization and share the
284 to document the policy used as well as any main project 340 same source directories on their machines.
285 guidelines so they are understood by everyone. 341 </para></listitem>
286 It is also a good idea to have well structured 342 <listitem><para>
287 commit messages, which are usually a part of a project's 343 Set up an Autobuilder and have it populate the
288 guidelines. 344 sstate cache and source directories.
289 Good commit messages are essential when looking back in time and 345 </para></listitem>
290 trying to understand why changes were made. 346 <listitem><para>
291 </para> 347 The Yocto Project community encourages you
292 348 to send patches to the project to fix bugs or add features.
293 <para> 349 If you do submit patches, follow the project commit
294 If you discover that changes are needed to the core layer of the 350 guidelines for writing good commit messages.
295 project, it is worth sharing those with the community as soon 351 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
296 as possible. 352 section.
297 Chances are if you have discovered the need for changes, someone 353 </para></listitem>
298 else in the community needs them also. 354 <listitem><para>
299 </para> 355 Send changes to the core sooner than later
300 </section> 356 as others are likely to run into the same issues.
301 357 For some guidance on mailing lists to use, see the list in the
302 <section id='best-practices-summary'> 358 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
303 <title>Summary</title> 359 section.
304 360 For a description of the available mailing lists, see the
305 <para> 361 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
306 This section summarizes the key recommendations described in the 362 section in the Yocto Project Reference Manual.
307 previous sections: 363 </para></listitem>
308 <itemizedlist> 364 </itemizedlist>
309 <listitem><para>Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> 365 </para></listitem>
310 as the source control system.</para></listitem> 366 </orderedlist>
311 <listitem><para>Maintain your Metadata in layers that make sense 367 </para>
312 for your situation.
313 See the "<link linkend='understanding-and-creating-layers'>Understanding
314 and Creating Layers</link>" section for more information on
315 layers.</para></listitem>
316 <listitem><para>
317 Separate the project's Metadata and code by using
318 separate Git repositories.
319 See the
320 "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
321 section for information on these repositories.
322 See the
323 "<link linkend='getting-setup'>Getting Set Up</link>"
324 section for information on how to set up local Git
325 repositories for related upstream Yocto Project
326 Git repositories.
327 </para></listitem>
328 <listitem><para>Set up the directory for the shared state cache
329 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
330 where it makes sense.
331 For example, set up the sstate cache on a system used
332 by developers in the same organization and share the
333 same source directories on their machines.
334 </para></listitem>
335 <listitem><para>Set up an Autobuilder and have it populate the
336 sstate cache and source directories.</para></listitem>
337 <listitem><para>The Yocto Project community encourages you
338 to send patches to the project to fix bugs or add features.
339 If you do submit patches, follow the project commit
340 guidelines for writing good commit messages.
341 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
342 section.</para></listitem>
343 <listitem><para>Send changes to the core sooner than later
344 as others are likely to run into the same issues.
345 For some guidance on mailing lists to use, see the list in the
346 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
347 section.
348 For a description of the available mailing lists, see the
349 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
350 section in the Yocto Project Reference Manual.
351 </para></listitem>
352 </itemizedlist>
353 </para>
354 </section>
355</section> 368</section>
356 369
357<section id='submitting-a-defect-against-the-yocto-project'> 370<section id='submitting-a-defect-against-the-yocto-project'>