Blame - yocto-poky/documentation/dev-manual/dev-manual-newbie.xml - mdmillerii/openbmc

"<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>"

918

section.

919

</para>

</section>

<para>

The Yocto Project makes extensive use of Git,

927

which is a free, open source distributed version control system.

928

Git supports distributed development, non-linear development, and can handle large projects.

929

It is best that you have some fundamental understanding of how Git tracks projects and

930

how to work with Git if you are going to use the Yocto Project for development.

931

This section provides a quick overview of how Git works and provides you with a summary

932

of some essential Git commands.

</para>

<para>

For more information on Git, see

937

<ulink url='http://git-scm.com/documentation'></ulink>.

938

If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.

</para>

<title>Repositories, Tags, and Branches</title>

943

944

<para>

945

As mentioned earlier in the section

946

"<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>",

947

the Yocto Project maintains source repositories at

948

<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.

949

If you look at this web-interface of the repositories, each item is a separate

Git repository.

</para>

<para>

Git repositories use branching techniques that track content change (not files)

955

within a project (e.g. a new feature or updated documentation).

956

Creating a tree-like structure based on project divergence allows for excellent historical

957

information over the life of a project.

958

This methodology also allows for an environment from which you can do lots of

959

local experimentation on projects as you develop changes or new features.

</para>

<para>

A Git repository represents all development efforts for a given project.

964

For example, the Git repository <filename>poky</filename> contains all changes

965

and developments for Poky over the course of its entire life.

966

That means that all changes that make up all releases are captured.

967

The repository maintains a complete history of changes.

</para>

<para>

You can create a local copy of any repository by "cloning" it with the Git

972

<filename>clone</filename> command.

973

When you clone a Git repository, you end up with an identical copy of the

974

repository on your development system.

975

Once you have a local copy of a repository, you can take steps to develop locally.

976

For examples on how to clone Git repositories, see the

977

"<link linkend='getting-setup'>Getting Set Up</link>" section.

</para>

<para>

It is important to understand that Git tracks content change and

982

not files.

983

Git uses "branches" to organize different development efforts.

984

For example, the <filename>poky</filename> repository has

985

several branches that include the current

986

<filename>&DISTRO_NAME;</filename> branch, the

987

<filename>master</filename> branch, and many branches for past

988

Yocto Project releases.

989

You can see all the branches by going to

990

<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and

991

clicking on the

992

993

link beneath the "Branch" heading.

</para>

<para>

Each of these branches represents a specific area of development.

998

The <filename>master</filename> branch represents the current or most recent

999

development.

1000

All other branches represent offshoots of the <filename>master</filename>

branch.

</para>

<para>

When you create a local copy of a Git repository, the copy has the same set

1006

of branches as the original.

1007

This means you can use Git to create a local working area (also called a branch)

1008

that tracks a specific development branch from the source Git repository.

1009

in other words, you can define your local Git environment to work on any development

1010

branch in the repository.

1011

To help illustrate, here is a set of commands that creates a local copy of the

1012

<filename>poky</filename> Git repository and then creates and checks out a local

1013

Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:

1014

1015

$ cd ~

1016

$ git clone git://git.yoctoproject.org/poky

1017

$ cd poky

1018

$ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;

1019

</literallayout>

1020

In this example, the name of the top-level directory of your local

1021

1022

is "poky" and the name of that local working area (local branch)

1023

you just created and checked out is "&DISTRO_NAME;".

1024

The files in your local repository now reflect the same files that

1025

are in the "&DISTRO_NAME;" development branch of the

1026

Yocto Project's "poky" upstream repository.

1027

It is important to understand that when you create and checkout a

1028

local working branch based on a branch name,

1029

your local environment matches the "tip" of that development branch

1030

at the time you created your local branch, which could be

1031

different from the files at the time of a similarly named release.

1032

In other words, creating and checking out a local branch based on

1033

the "&DISTRO_NAME;" branch name is not the same as

1034

cloning and checking out the "master" branch.

1035

Keep reading to see how you create a local snapshot of a Yocto

Project Release.

</para>

<para>

Git uses "tags" to mark specific changes in a repository.

1041

Typically, a tag is used to mark a special point such as the final

1042

change before a project is released.

1043

You can see the tags used with the <filename>poky</filename> Git

1044

repository by going to

1045

<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and

1046

clicking on the

1047

1048

link beneath the "Tag" heading.

</para>

<para>

Some key tags are <filename>dylan-9.0.4</filename>,

1053

<filename>dora-10.0.4</filename>, <filename>daisy-11.0.2</filename>,

1054

<filename>dizzy-12.0.0</filename>, and

1055

<filename>&DISTRO_NAME;-&POKYVERSION;</filename>.

1056

These tags represent Yocto Project releases.

</para>

<para>

When you create a local copy of the Git repository, you also have access to all the

1061

tags.

1062

Similar to branches, you can create and checkout a local working Git branch based

1063

on a tag name.

1064

When you do this, you get a snapshot of the Git repository that reflects

1065

the state of the files when the change was made associated with that tag.

1066

The most common use is to checkout a working branch that matches a specific

1067

Yocto Project release.

Here is an example:

$ cd ~

$ git clone git://git.yoctoproject.org/poky

1072

$ cd poky

1073

$ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION;

1074

</literallayout>

1075

In this example, the name of the top-level directory of your local Yocto Project

1076

Files Git repository is <filename>poky</filename>.

1077

And, the name of the local branch you have created and checked out is

1078

<filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>.

1079

The files in your repository now exactly match the Yocto Project &DISTRO;

1080

Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>).

1081

It is important to understand that when you create and checkout a local

1082

working branch based on a tag, your environment matches a specific point

1083

in time and not the entire development branch.

</para>

</section>

<title>Basic Commands</title>

1089

1090

<para>

1091

Git has an extensive set of commands that lets you manage changes and perform

1092

collaboration over the life of a project.

1093

Conveniently though, you can manage with a small set of basic operations and workflows

1094

once you understand the basic philosophy behind Git.

1095

You do not have to be an expert in Git to be functional.

1096

A good place to look for instruction on a minimal set of Git commands is

1097

<ulink url='http://git-scm.com/documentation'>here</ulink>.

1098

If you need to download Git, you can do so

1099

<ulink url='http://git-scm.com/download'>here</ulink>, although

1100

any reasonably current Linux distribution should already have an

1101

installable package for Git.

</para>

<para>

If you do not know much about Git, you should educate

1106

yourself by visiting the links previously mentioned.

</para>

<para>

The following list briefly describes some basic Git operations as a way to get started.

1111

As with any set of commands, this list (in most cases) simply shows the base command and

1112

omits the many arguments they support.

1113

See the Git documentation for complete descriptions and strategies on how to use these commands:

1114

1115

<listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.

1116

You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>

1117

<listitem><para><emphasis><filename>git clone</filename>:</emphasis>

1118

Creates a local clone of a Git repository.

1119

During collaboration, this command allows you to create a

1120

local Git repository that is on equal footing with a fellow

1121

developer’s Git repository.

1122

</para></listitem>

1123

<listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents

1124

to the index that

1125

Git uses to track changes.

1126

You must stage all files that have changed before you can commit them.</para></listitem>

1127

<listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a "commit" that documents

1128

the changes you made.

1129

Commits are used for historical purposes, for determining if a maintainer of a project

1130

will allow the change, and for ultimately pushing the change from your local Git repository

1131

into the project’s upstream (or master) repository.</para></listitem>

1132

<listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that

1133

possibly need to be staged and committed.</para></listitem>

1134

<listitem><para><emphasis><filename>git checkout <branch-name></filename>:</emphasis> Changes

1135

your working branch.

1136

This command is analogous to "cd".</para></listitem>

1137

<listitem><para><emphasis><filename>git checkout –b <working-branch></filename>:</emphasis> Creates

1138

a working branch on your local machine where you can isolate work.

1139

It is a good idea to use local branches when adding specific features or changes.

1140

This way if you do not like what you have done you can easily get rid of the work.</para></listitem>

1141

<listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports

1142

existing local branches and

1143

tells you the branch in which you are currently working.</para></listitem>

1144

<listitem><para><emphasis><filename>git branch -D <branch-name></filename>:</emphasis>

1145

Deletes an existing local branch.

1146

You need to be in a local branch other than the one you are deleting

1147

in order to delete <filename><branch-name></filename>.</para></listitem>

1148

<listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information

1149

from an upstream Git

1150

repository and places it in your local Git repository.

1151

You use this command to make sure you are synchronized with the repository

1152

from which you are basing changes (.e.g. the master branch).</para></listitem>

1153

1154

Sends all your committed local changes to an upstream Git

1155

repository (e.g. a contribution repository).

1156

The maintainer of the project draws from these repositories

1157

when adding changes to the project’s master repository or

1158

other development branch.

1159

</para></listitem>

1160

<listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one

1161

local branch of your repository with another branch.

1162

When you create a local Git repository, the default branch is named "master".

1163

A typical workflow is to create a temporary branch for isolated work, make and commit your

1164

changes, switch to your local master branch, merge the changes from the temporary branch into the

1165

local master branch, and then delete the temporary branch.</para></listitem>

1166

<listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific

1167

commits from one branch into another branch.

1168

There are times when you might not be able to merge all the changes in one branch with

1169

another but need to pick out certain ones.</para></listitem>

1170

<listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches

1171

and changes in your local Git repository.

1172

This command is a good way to graphically see where things have diverged in your

1173

local repository.</para></listitem>

1174

<listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the

1175

repository.</para></listitem>

1176

<listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences

1177

between your local working files and the same files in the upstream Git repository that your

1178

branch currently tracks.</para></listitem>

</itemizedlist>

</para>

</section>

</section>

<title>Workflows</title>

1186

1187

<para>

1188

This section provides some overview on workflows using Git.

1189

In particular, the information covers basic practices that describe roles and actions in a

1190

collaborative development environment.

1191

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

1197

tracks every change and whose structure provides branches for all diverging functionality.

1198

Although there is no need to use Git, many open source projects do so.

1199

For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"

1200

branch of a given Git repository.

1201

The "master" branch is the “upstream” repository where the final builds of the project occur.

1202

The maintainer is responsible for accepting changes from other developers and for

1203

organizing the underlying branch structure to reflect release strategies and so forth.

1204

<note>For information on finding out who is responsible for (maintains)

1205

a particular area of code, see the

1206

"<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

1213

<filename>poky-contrib</filename>.

1214

You can see all the branches in this repository using the web interface

1215

of the

1216

<ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized

1217

within the "Poky Support" area.

1218

These branches temporarily hold changes to the project that have been

1219

submitted or committed by the Yocto Project development team and by

1220

community members who contribute to the project.

1221

The maintainer determines if the changes are qualified to be moved

1222

from the "contrib" branches into the "master" branch of the Git

repository.

</para>

<para>

Developers (including contributing community members) create and maintain cloned repositories

1228

of the upstream "master" branch.

1229

These repositories are local to their development platforms and are used to develop changes.

1230

When a developer is satisfied with a particular feature or change, they "push" the changes

1231

to the appropriate "contrib" repository.

</para>

<para>

Developers are responsible for keeping their local repository up-to-date with "master".

1236

They are also responsible for straightening out any conflicts that might arise within files

1237

that are being worked on simultaneously by more than one person.

1238

All this work is done locally on the developer’s machines before anything is pushed to a

1239

"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

1244

"contrib" area and subsequently request that the maintainer include them into "master"

1245

This process is called “submitting a patch” or "submitting a change."

1246

For information on submitting patches and changes, see the

1247

"<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

1252

changes into the project’s "master" branch of the Git repository,

1253

which is controlled by the project’s maintainer.

1254

And, a set of developers exist who independently develop, test, and

1255

submit changes to "contrib" areas for the maintainer to examine.

1256

The maintainer then chooses which changes are going to become a

1257

permanent part of the project.

</para>

<para>

</para>

<para>

While each development environment is unique, there are some best practices or methods

1266

that help development run smoothly.

1267

The following list describes some of these practices.

1268

For more information about Git workflows, see the workflow topics in the

1269

<ulink url='http://book.git-scm.com'>Git Community Book</ulink>.

1270

1271

<listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit

1272

small as compared to bundling many disparate changes into a single commit.

1273

This practice not only keeps things manageable but also allows the maintainer

1274

to more easily include or refuse changes.</para>

1275

<para>It is also good practice to leave the repository in a state that allows you to

1276

still successfully build your project. In other words, do not commit half of a feature,

1277

then add the other half as a separate, later commit.

1278

Each commit should take you from one buildable project state to another

1279

buildable state.</para></listitem>

1280

<listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and

1281

delete local branches in your working Git repository.

1282

You can name these branches anything you like.

1283

It is helpful to give them names associated with the particular feature or change

1284

on which you are working.

1285

Once you are done with a feature or change and have merged it

1286

into your local master branch, simply discard the temporary

1287

branch.</para></listitem>

1288

<listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>

1289

command allows you to take the

1290

changes from one branch and fold them into another branch.

1291

This process is especially helpful when more than a single developer might be working

1292

on different parts of the same feature.

1293

Merging changes also automatically identifies any collisions or "conflicts"

1294

that might happen as a result of the same lines of code being altered by two different

1295

developers.</para></listitem>

1296

<listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should

1297

use a system where branches indicate varying levels of code readiness.

1298

For example, you can have a "work" branch to develop in, a "test" branch where the code or

1299

change is tested, a "stage" branch where changes are ready to be committed, and so forth.

1300

As your project develops, you can merge code across the branches to reflect ever-increasing

1301

stable states of the development.</para></listitem>

1302

<listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the

1303

concept of developers "pushing" local commits to a remote repository, which is

1304

usually a contribution repository.

1305

This workflow is also based on developers "pulling" known states of the project down into their

1306

local development repositories.

1307

The workflow easily allows you to pull changes submitted by other developers from the

1308

upstream repository into your work area ensuring that you have the most recent software

1309

on which to develop.

1310

The Yocto Project has two scripts named <filename>create-pull-request</filename> and

1311

<filename>send-pull-request</filename> that ship with the release to facilitate this

1312

workflow.

1313

You can find these scripts in the <filename>scripts</filename>

1314

folder of the

1315

1316

For information on how to use these scripts, see the

1317

"<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.

1318

</para></listitem>

1319

<listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the

1320

maintainer through an email that you have a change (or patch) you would like considered

1321

for the "master" branch of the Git repository.

1322

To send this type of change, you format the patch and then send the email using the Git commands

1323

<filename>git format-patch</filename> and <filename>git send-email</filename>.

1324

For information on how to use these scripts, see the

1325

"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"

section.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Tracking Bugs</title>

1334

1335

<para>

1336

The Yocto Project uses its own implementation of

1337

<ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs.

1338

Implementations of Bugzilla work well for group development because they track bugs and code

1339

changes, can be used to communicate changes and problems with developers, can be used to

1340

submit and review patches, and can be used to manage quality assurance.

1341

The home page for the Yocto Project implementation of Bugzilla is

1342

<ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.

</para>

<para>

Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself

1347

such as when discovering an issue with some component of the build system that acts contrary

1348

to the documentation or your expectations.

1349

Following is the general procedure for submitting a new bug using the Yocto Project

1350

Bugzilla.

1351

You can find more information on defect management, bug tracking, and feature request

1352

processes all accomplished through the Yocto Project Bugzilla on the

1353

<ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>.

1354

1355

<listitem><para>Always use the Yocto Project implementation of Bugzilla to submit

1356

a bug.</para></listitem>

1357

<listitem><para>When submitting a new bug, be sure to choose the appropriate

1358

Classification, Product, and Component for which the issue was found.

1359

Defects for the Yocto Project fall into one of seven classifications:

1360

Yocto Project Components, Infrastructure, Build System & Metadata,

1361

Documentation, QA/Testing, Runtime and Hardware.

1362

Each of these Classifications break down into multiple Products and, in some

1363

cases, multiple Components.</para></listitem>

1364

<listitem><para>Use the bug form to choose the correct Hardware and Architecture

1365

for which the bug applies.</para></listitem>

1366

<listitem><para>Indicate the Yocto Project version you were using when the issue

1367

occurred.</para></listitem>

1368

<listitem><para>Be sure to indicate the Severity of the bug.

1369

Severity communicates how the bug impacted your work.</para></listitem>

1370

<listitem><para>Select the appropriate "Documentation change" item

1371

for the bug.

1372

Fixing a bug may or may not affect the Yocto Project

1373

documentation.</para></listitem>

1374

<listitem><para>Provide a brief summary of the issue.

1375

Try to limit your summary to just a line or two and be sure to capture the

1376

essence of the issue.</para></listitem>

1377

<listitem><para>Provide a detailed description of the issue.

1378

You should provide as much detail as you can about the context, behavior, output,

1379

and so forth that surrounds the issue.

1380

You can even attach supporting files for output from logs by

1381

using the "Add an attachment" button.</para></listitem>

1382

<listitem><para>Be sure to copy the appropriate people in the

1383

"CC List" for the bug.

1384

See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"

1385

section for information about finding out who is responsible

1386

for code.</para></listitem>

1387

<listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>

</orderedlist>

</para>

</section>

<title>How to Submit a Change</title>

1394

1395

<para>

1396

Contributions to the Yocto Project and OpenEmbedded are very welcome.

1397

Because the system is extremely configurable and flexible, we recognize that developers

1398

will want to extend, configure or optimize it for their specific uses.

1399

You should send patches to the appropriate mailing list so that they

1400

can be reviewed and merged by the appropriate maintainer.

</para>

<para>

Before submitting any change, be sure to find out who you should be

1405

notifying.

1406

Several methods exist through which you find out who you should be copying

1407

or notifying:

1408

1409

<listitem><para><emphasis>Maintenance File:</emphasis>

1410

Examine the <filename>maintainers.inc</filename> file, which is

1411

located in the

1412

1413

at <filename>meta-yocto/conf/distro/include</filename>, to

1414

see who is responsible for code.

1415

</para></listitem>

1416

<listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis>

1417

For BSP maintainers of supported BSPs, you can examine

1418

individual BSP <filename>README</filename> files.

1419

In addition, some layers (such as the <filename>meta-intel</filename> layer),

1420

include a <filename>MAINTAINERS</filename> file which contains

1421

a list of all supported BSP maintainers for that layer.

1422

</para></listitem>

1423

<listitem><para><emphasis>Search by File:</emphasis>

1424

Using <link linkend='git'>Git</link>, you can enter the

1425

following command to bring up a short list of all commits

1426

against a specific file:

1427

1428

git shortlog -- <replaceable>filename</replaceable>

1429

</literallayout>

1430

Just provide the name of the file for which you are interested.

1431

The information returned is not ordered by history but does

1432

include a list of all committers grouped by name.

1433

From the list, you can see who is responsible for the bulk of

1434

the changes against the file.

</para></listitem>

</itemizedlist>

</para>

<para>

For a list of the Yocto Project and related mailing lists, see the

1441

"<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in

1442

the Yocto Project Reference Manual.

</para>

<para>

Here is some guidance on which mailing list to use for what type of change:

1447

1448

<listitem><para>For changes to the core

1449

1450

<ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.

1451

For example, a change to anything under the <filename>meta</filename> or

1452

<filename>scripts</filename> directories

1453

should be sent to this mailing list.</para></listitem>

1454

<listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>

1455

directory), send your patch to the

1456

<ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>

1457

<listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the

1458

<ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>

1459

<listitem><para>For changes to other layers hosted on

1460

<filename>yoctoproject.org</filename> (unless the

1461

layer's documentation specifies otherwise), tools, and Yocto Project

1462

documentation, use the

1463

<ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>

1464

<listitem><para>For additional recipes that do not fit into the core Metadata,

1465

you should determine which layer the recipe should go into and submit the

1466

change in the manner recommended by the documentation (e.g. README) supplied

1467

with the layer. If in doubt, please ask on the

1468

<ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or

1469

<ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>

1470

mailing lists.</para></listitem>

</itemizedlist>

</para>

<para>

When you send a patch, be sure to include a "Signed-off-by:"

1476

line in the same style as required by the Linux kernel.

1477

Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1

1478

as follows:

1479

1480

Developer's Certificate of Origin 1.1

1481

1482

By making a contribution to this project, I certify that:

1483

1484

(a) The contribution was created in whole or in part by me and I

1485

have the right to submit it under the open source license

1486

indicated in the file; or

1487

1488

(b) The contribution is based upon previous work that, to the best

1489

of my knowledge, is covered under an appropriate open source

1490

license and I have the right under that license to submit that

1491

work with modifications, whether created in whole or in part

1492

by me, under the same open source license (unless I am

1493

permitted to submit under a different license), as indicated

1494

in the file; or

1495

1496

(c) The contribution was provided directly to me by some other

1497

person who certified (a), (b) or (c) and I have not modified

1498

it.

1499

1500

(d) I understand and agree that this project and the contribution

1501

are public and that a record of the contribution (including all

1502

personal information I submit with it, including my sign-off) is

1503

maintained indefinitely and may be redistributed consistent with

1504

this project or the open source license(s) involved.

</literallayout>

</para>

<para>

In a collaborative environment, it is necessary to have some sort of standard

1510

or method through which you submit changes.

1511

Otherwise, things could get quite chaotic.

1512

One general practice to follow is to make small, controlled changes.

1513

Keeping changes small and isolated aids review, makes merging/rebasing easier

1514

and keeps the change history clean when anyone needs to refer to it in future.

</para>

<para>

When you make a commit, you must follow certain standards established by the

1519

OpenEmbedded and Yocto Project development teams.

1520

For each commit, you must provide a single-line summary of the change and you

1521

should almost always provide a more detailed description of what you did (i.e.

1522

the body of the commit message).

1523

The only exceptions for not providing a detailed description would be if your

1524

change is a simple, self-explanatory change that needs no further description

1525

beyond the summary.

1526

Here are the guidelines for composing a commit message:

1527

1528

<listitem><para>Provide a single-line, short summary of the change.

1529

This summary is typically viewable in the "shortlist" of changes.

1530

Thus, providing something short and descriptive that gives the reader

1531

a summary of the change is useful when viewing a list of many commits.

1532

This short description should be prefixed by the recipe name (if changing a recipe), or

1533

else the short form path to the file being changed.

1534

</para></listitem>

1535

<listitem><para>For the body of the commit message, provide detailed information

1536

that describes what you changed, why you made the change, and the approach

1537

you used. It may also be helpful if you mention how you tested the change.

1538

Provide as much detail as you can in the body of the commit message.

1539

</para></listitem>

1540

1541

If the change addresses a specific bug or issue that is

1542

associated with a bug-tracking ID, include a reference to that

1543

ID in your detailed description.

1544

For example, the Yocto Project uses a specific convention for

1545

bug references - any commit that addresses a specific bug should

1546

use the following form for the detailed description:

1547

1548

Fixes [YOCTO #<replaceable>bug-id</replaceable>]

1549

1550

<replaceable>detailed description of change</replaceable>

1551

</literallayout></para></listitem>

1552

Where <replaceable>bug-id</replaceable> is replaced with the

1553

specific bug ID from the Yocto Project Bugzilla instance.

</itemizedlist>

</para>

<para>

You can find more guidance on creating well-formed commit messages at this OpenEmbedded

1559

wiki page:

1560

<ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.

</para>

<para>

The next two sections describe general instructions for both pushing

1565

changes upstream and for submitting changes as patches.

</para>

<title>Using Scripts to Push a Change Upstream and Request a Pull</title>

1570

1571

<para>

1572

The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:

1573

1574

<listitem><para>Make your changes in your local Git repository.</para></listitem>

1575

<listitem><para>Stage your changes by using the <filename>git add</filename>

1576

command on each file you changed.</para></listitem>

1577

1578

Commit the change by using the

1579

<filename>git commit</filename> command.

1580

Be sure to provide a commit message that follows the

1581

project’s commit message standards as described earlier.

1582

</para></listitem>

1583

1584

Push the change to the upstream "contrib" repository by

1585

using the <filename>git push</filename> command.

1586

</para></listitem>

1587

<listitem><para>Notify the maintainer that you have pushed a change by making a pull

1588

request.

1589

The Yocto Project provides two scripts that conveniently let you generate and send

1590

pull requests to the Yocto Project.

1591

These scripts are <filename>create-pull-request</filename> and

1592

<filename>send-pull-request</filename>.

1593

You can find these scripts in the <filename>scripts</filename> directory

1594

within the <link linkend='source-directory'>Source Directory</link>.</para>

1595

<para>Using these scripts correctly formats the requests without introducing any

1596

whitespace or HTML formatting.

1597

The maintainer that receives your patches needs to be able to save and apply them

1598

directly from your emails.

1599

Using these scripts is the preferred method for sending patches.</para>

1600

<para>For help on using these scripts, simply provide the

1601

<filename>-h</filename> argument as follows:

1602

1603

$ poky/scripts/create-pull-request -h

1604

$ poky/scripts/send-pull-request -h

1605

</literallayout></para></listitem>

</itemizedlist>

</para>

<para>

You can find general Git information on how to push a change upstream in the

1611

<ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.

</para>

</section>

<title>Using Email to Submit a Patch</title>

1617

1618

<para>

1619

You can submit patches without using the <filename>create-pull-request</filename> and

1620

<filename>send-pull-request</filename> scripts described in the previous section.

1621

However, keep in mind, the preferred method is to use the scripts.

</para>

<para>

Depending on the components changed, you need to submit the email to a specific

1626

mailing list.

1627

For some guidance on which mailing list to use, see the list in the

1628

"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"

1629

section.

1630

For a description of the available mailing lists, see the

1631

"<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"

1632

section in the Yocto Project Reference Manual.

</para>

<para>

Here is the general procedure on how to submit a patch through email without using the

1637

scripts:

1638

1639

<listitem><para>Make your changes in your local Git repository.</para></listitem>

1640

<listitem><para>Stage your changes by using the <filename>git add</filename>

1641

command on each file you changed.</para></listitem>

1642

<listitem><para>Commit the change by using the

1643

<filename>git commit --signoff</filename> command.

1644

Using the <filename>--signoff</filename> option identifies you as the person

1645

making the change and also satisfies the Developer's Certificate of

1646

Origin (DCO) shown earlier.</para>

1647

<para>When you form a commit, you must follow certain standards established by the

1648

Yocto Project development team.

1649

See the earlier section

1650

"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"

1651

for Yocto Project commit message standards.</para></listitem>

1652

<listitem><para>Format the commit into an email message.

1653

To format commits, use the <filename>git format-patch</filename> command.

1654

When you provide the command, you must include a revision list or a number of patches

1655

as part of the command.

1656

For example, either of these two commands takes your most

1657

recent single commit and formats it as an email message in

1658

the current directory:

1659

1660

$ git format-patch -1

</literallayout>

or

$ git format-patch HEAD~

1665

</literallayout></para>

1666

<para>After the command is run, the current directory contains a

1667

numbered <filename>.patch</filename> file for the commit.</para>

1668

<para>If you provide several commits as part of the command,

1669

the <filename>git format-patch</filename> command produces a

1670

series of numbered files in the current directory – one for each commit.

1671

If you have more than one patch, you should also use the

1672

<filename>--cover</filename> option with the command, which generates a

1673

cover letter as the first "patch" in the series.

1674

You can then edit the cover letter to provide a description for

1675

the series of patches.

1676

For information on the <filename>git format-patch</filename> command,

1677

see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the

1678

<filename>man git-format-patch</filename> command.</para>

1679

<note>If you are or will be a frequent contributor to the Yocto Project

1680

or to OpenEmbedded, you might consider requesting a contrib area and the

1681

necessary associated rights.</note></listitem>

1682

<listitem><para>Import the files into your mail client by using the

1683

<filename>git send-email</filename> command.

1684

<note>In order to use <filename>git send-email</filename>, you must have the

1685

the proper Git packages installed.

1686

For Ubuntu, Debian, and Fedora the package is <filename>git-email</filename>.</note></para>

1687

<para>The <filename>git send-email</filename> command sends email by using a local

1688

or remote Mail Transport Agent (MTA) such as

1689

<filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct

1690

<filename>smtp</filename> configuration in your Git <filename>config</filename>

1691

file.

1692

If you are submitting patches through email only, it is very important

1693

that you submit them without any whitespace or HTML formatting that

1694

either you or your mailer introduces.

1695

The maintainer that receives your patches needs to be able to save and

1696

apply them directly from your emails.

1697

A good way to verify that what you are sending will be applicable by the

1698

maintainer is to do a dry run and send them to yourself and then

1699

save and apply them as the maintainer would.</para>

1700

<para>The <filename>git send-email</filename> command is the preferred method

1701

for sending your patches since there is no risk of compromising whitespace

1702

in the body of the message, which can occur when you use your own mail client.

1703

The command also has several options that let you

1704

specify recipients and perform further editing of the email message.

1705

For information on how to use the <filename>git send-email</filename> command,

1706

see <filename>GIT-SEND-EMAIL(1)</filename> displayed using

1707

the <filename>man git-send-email</filename> command.

</para></listitem>

</itemizedlist>

</para>

</section>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

1716

-->