summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml362
1 files changed, 234 insertions, 128 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 75c992f16b..4fd0d3a60c 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -1394,83 +1394,182 @@
1394 can be reviewed and merged by the appropriate maintainer. 1394 can be reviewed and merged by the appropriate maintainer.
1395 </para> 1395 </para>
1396 1396
1397 <para> 1397 <section id='submit-change-overview'>
1398 Before submitting any change, be sure to find out who you should be 1398 <title>Overview</title>
1399 notifying.
1400 Several methods exist through which you find out who you should be copying
1401 or notifying:
1402 <itemizedlist>
1403 <listitem><para><emphasis>Maintenance File:</emphasis>
1404 Examine the <filename>maintainers.inc</filename> file, which is
1405 located in the
1406 <link linkend='source-directory'>Source Directory</link>
1407 at <filename>meta-poky/conf/distro/include</filename>, to
1408 see who is responsible for code.
1409 </para></listitem>
1410 <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis>
1411 For BSP maintainers of supported BSPs, you can examine
1412 individual BSP <filename>README</filename> files.
1413 In addition, some layers (such as the <filename>meta-intel</filename> layer),
1414 include a <filename>MAINTAINERS</filename> file which contains
1415 a list of all supported BSP maintainers for that layer.
1416 </para></listitem>
1417 <listitem><para><emphasis>Search by File:</emphasis>
1418 Using <link linkend='git'>Git</link>, you can enter the
1419 following command to bring up a short list of all commits
1420 against a specific file:
1421 <literallayout class='monospaced'>
1422 git shortlog -- <replaceable>filename</replaceable>
1423 </literallayout>
1424 Just provide the name of the file for which you are interested.
1425 The information returned is not ordered by history but does
1426 include a list of all committers grouped by name.
1427 From the list, you can see who is responsible for the bulk of
1428 the changes against the file.
1429 </para></listitem>
1430 </itemizedlist>
1431 </para>
1432 1399
1433 <para> 1400 <para>
1434 For a list of the Yocto Project and related mailing lists, see the 1401 The Yocto Project uses a mailing list and patch-based workflow
1435 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in 1402 that is similar to the Linux kernel but contains important
1436 the Yocto Project Reference Manual. 1403 differences.
1437 </para> 1404 In general, a mailing list exists through which you can submit
1405 patches.
1406 The specific mailing list you need to use depends on the
1407 location of the code you are changing.
1408 Each component (e.g. layer) should have a
1409 <filename>README</filename> file that indicates where to send
1410 the changes and which process to follow.
1411 </para>
1438 1412
1439 <para> 1413 <para>
1440 Here is some guidance on which mailing list to use for what type of change: 1414 You can send the patch to the mailing list using whichever approach
1441 <itemizedlist> 1415 you feel comfortable with to generate the patch.
1442 <listitem><para>For changes to the core 1416 Once sent, the patch is usually reviewed by the community at large.
1443 <link linkend='metadata'>Metadata</link>, send your patch to the 1417 If somebody has concerns with the patch, they will usually voice
1444 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list. 1418 their concern over the mailing list.
1445 For example, a change to anything under the <filename>meta</filename> or 1419 If a patch does not receive any negative reviews, the maintainer of
1446 <filename>scripts</filename> directories 1420 the affected layer typically takes the patch, tests it, and then
1447 should be sent to this mailing list.</para></listitem> 1421 based on successful testing, merges the patch.
1448 <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename> 1422 </para>
1449 directory), send your patch to the
1450 <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
1451 <listitem><para>For changes to <filename>meta-poky</filename>, send your patch to the
1452 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
1453 <listitem><para>For changes to other layers hosted on
1454 <filename>yoctoproject.org</filename> (unless the
1455 layer's documentation specifies otherwise), tools, and Yocto Project
1456 documentation, use the
1457 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
1458 <listitem><para>For additional recipes that do not fit into the core Metadata,
1459 you should determine which layer the recipe should go into and submit the
1460 change in the manner recommended by the documentation (e.g. README) supplied
1461 with the layer. If in doubt, please ask on the
1462 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
1463 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
1464 mailing lists.</para></listitem>
1465 </itemizedlist>
1466 </para>
1467 1423
1468 <para> 1424 <para>
1469 When you send a patch, be sure to include a "Signed-off-by:" 1425 Specific to OpenEmbedded-Core, two commonly used testing trees
1470 line in the same style as required by the Linux kernel. 1426 exist:
1471 Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 1427 <itemizedlist>
1472 as follows: 1428 <listitem><para>
1473 <literallayout class='monospaced'> 1429 <emphasis>"ross/mut" branch:</emphasis>
1430 The "mut" (master-under-test) tree
1431 exists in the <filename>poky-contrib</filename> repository
1432 in the
1433 <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
1434 </para></listitem>
1435 <listitem><para>
1436 <emphasis>"master-next" branch:</emphasis>
1437 This branch is part of the main
1438 "poky" repository in the Yocto Project source repositories.
1439 </para></listitem>
1440 </itemizedlist>
1441 Maintainers use these branches to test submissions prior to merging
1442 patches.
1443 Thus, you can get an idea of the status of a patch based on
1444 whether the patch has been merged into one of these branches.
1445 </para>
1446
1447 <para>
1448 This system is imperfect and patches can sometimes get lost in the
1449 flow.
1450 Asking about the status of a patch is reasonable if the patch
1451 has been idle for a while with no feedback.
1452 The Yocto Project does have plans to use
1453 <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
1454 to track the status of patches and also to automatically preview
1455 patches.
1456 </para>
1457
1458 <para>
1459 The following sections provide general instructions for both
1460 pushing changes upstream and for submitting changes as patches.
1461 </para>
1462 </section>
1463
1464 <section id='submit-change-submissions-to-poky'>
1465 <title>Submissions to Poky</title>
1466
1467 <para>
1468 The "poky" repository, which is the Yocto Project's reference build
1469 environment, is a hybrid repository that contains several
1470 individual pieces (e.g. BitBake, OpenEmbedded-Core, meta-yocto,
1471 documentation, and so forth) built using the combo-layer tool.
1472 The upstream location used for submitting changes varies by
1473 component:
1474 <itemizedlist>
1475 <listitem><para>
1476 <emphasis>Core Metadata:</emphasis>
1477 Send your patch to the
1478 <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
1479 mailing list. For example, a change to anything under
1480 the <filename>meta</filename> or
1481 <filename>scripts</filename> directories should be sent
1482 to this mailing list.
1483 </para></listitem>
1484 <listitem><para>
1485 <emphasis>BitBake:</emphasis>
1486 For changes to BitBake (i.e. anything under the
1487 <filename>bitbake</filename> directory), send your patch
1488 to the
1489 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
1490 mailing list.
1491 </para></listitem>
1492 <listitem><para>
1493 <emphasis>"meta-yocto-bsp" and "meta-poky" trees:</emphasis>
1494 These trees are
1495 part of the "meta-yocto" repository in the Yocto Project
1496 source repositories.
1497 Use the
1498 <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
1499 mailing list.
1500 </para></listitem>
1501 </itemizedlist>
1502 </para>
1503 </section>
1504
1505 <section id='submit-change-submissions-to-other-layers'>
1506 <title>Submissions to Other Layers</title>
1507
1508 <para>
1509 For changes to other layers hosted in the Yocto Project source
1510 repositories (i.e. <filename>yoctoproject.org</filename>), tools,
1511 and the Yocto Project documentation, use the
1512 <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
1513 general mailing list.
1514 <note>
1515 Sometimes a layer's documentation specifies to use a
1516 particular mailing list.
1517 If so, use that list.
1518 </note>
1519 For additional recipes that do not fit into the core Metadata, you
1520 should determine which layer the recipe should go into and submit
1521 the change in the manner recommended by the documentation (e.g.
1522 the <filename>README</filename> file) supplied with the layer.
1523 If in doubt, please ask on the Yocto general mailing list or on
1524 the openembedded-devel mailing list.
1525 </para>
1526 </section>
1527
1528 <section id='submit-change-patch-submission-details'>
1529 <title>Patch Submission Details</title>
1530
1531 <para>
1532 When submitting any change, you can check who you should be
1533 notifying.
1534 Use either of these methods to find out:
1535 <itemizedlist>
1536 <listitem><para>
1537 <emphasis>Maintenance File:</emphasis>
1538 Examine the <filename>maintainers.inc</filename> file, which is
1539 located in the
1540 <link linkend='source-directory'>Source Directory</link>
1541 at <filename>meta-poky/conf/distro/include</filename>, to
1542 see who is responsible for code.
1543 </para></listitem>
1544 <listitem><para>
1545 <emphasis>Search by File:</emphasis>
1546 Using <link linkend='git'>Git</link>, you can enter the
1547 following command to bring up a short list of all commits
1548 against a specific file:
1549 <literallayout class='monospaced'>
1550 git shortlog -- <replaceable>filename</replaceable>
1551 </literallayout>
1552 Just provide the name of the file for which you are interested.
1553 The information returned is not ordered by history but does
1554 include a list of all committers grouped by name.
1555 From the list, you can see who is responsible for the bulk of
1556 the changes against the file.
1557 </para></listitem>
1558 </itemizedlist>
1559 </para>
1560
1561 <para>
1562 For a list of the Yocto Project and related mailing lists, see the
1563 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
1564 section in the Yocto Project Reference Manual.
1565 </para>
1566
1567 <para>
1568 When you send a patch, be sure to include a "Signed-off-by:"
1569 line in the same style as required by the Linux kernel.
1570 Adding this line signifies that you, the submitter, have agreed
1571 to the Developer's Certificate of Origin 1.1 as follows:
1572 <literallayout class='monospaced'>
1474 Developer's Certificate of Origin 1.1 1573 Developer's Certificate of Origin 1.1
1475 1574
1476 By making a contribution to this project, I certify that: 1575 By making a contribution to this project, I certify that:
@@ -1496,68 +1595,75 @@
1496 personal information I submit with it, including my sign-off) is 1595 personal information I submit with it, including my sign-off) is
1497 maintained indefinitely and may be redistributed consistent with 1596 maintained indefinitely and may be redistributed consistent with
1498 this project or the open source license(s) involved. 1597 this project or the open source license(s) involved.
1499 </literallayout> 1598 </literallayout>
1500 </para> 1599 </para>
1501 1600
1502 <para> 1601 <para>
1503 In a collaborative environment, it is necessary to have some sort of standard 1602 In a collaborative environment, it is necessary to have some sort
1504 or method through which you submit changes. 1603 of standard or method through which you submit changes.
1505 Otherwise, things could get quite chaotic. 1604 Otherwise, things could get quite chaotic.
1506 One general practice to follow is to make small, controlled changes. 1605 One general practice to follow is to make small, controlled changes.
1507 Keeping changes small and isolated aids review, makes merging/rebasing easier 1606 Keeping changes small and isolated aids review, makes
1508 and keeps the change history clean when anyone needs to refer to it in future. 1607 merging/rebasing easier and keeps the change history clean should
1509 </para> 1608 anyone need to refer to it in future.
1609 </para>
1510 1610
1511 <para> 1611 <para>
1512 When you make a commit, you must follow certain standards established by the 1612 When you make a commit, you must follow certain standards
1513 OpenEmbedded and Yocto Project development teams. 1613 established by the OpenEmbedded and Yocto Project development teams.
1514 For each commit, you must provide a single-line summary of the change and you 1614 For each commit, you must provide a single-line summary of the
1515 should almost always provide a more detailed description of what you did (i.e. 1615 change and you should almost always provide a more detailed
1516 the body of the commit message). 1616 description of what you did (i.e. the body of the commit message).
1517 The only exceptions for not providing a detailed description would be if your 1617 The only exceptions for not providing a detailed description would
1518 change is a simple, self-explanatory change that needs no further description 1618 be if your change is a simple, self-explanatory change that needs
1519 beyond the summary. 1619 no further description beyond the summary.
1520 Here are the guidelines for composing a commit message: 1620 Here are the guidelines for composing a commit message:
1521 <itemizedlist> 1621 <itemizedlist>
1522 <listitem><para>Provide a single-line, short summary of the change. 1622 <listitem><para>
1523 This summary is typically viewable in the "shortlist" of changes. 1623 Provide a single-line, short summary of the change.
1524 Thus, providing something short and descriptive that gives the reader 1624 This summary is typically viewable in the "shortlist" of
1525 a summary of the change is useful when viewing a list of many commits. 1625 changes.
1526 This short description should be prefixed by the recipe name (if changing a recipe), or 1626 Thus, providing something short and descriptive that
1527 else the short form path to the file being changed. 1627 gives the reader a summary of the change is useful when
1528 </para></listitem> 1628 viewing a list of many commits.
1529 <listitem><para>For the body of the commit message, provide detailed information 1629 You should prefix this short description with the recipe
1530 that describes what you changed, why you made the change, and the approach 1630 name (if changing a recipe), or else with the short form
1531 you used. It may also be helpful if you mention how you tested the change. 1631 path to the file being changed.
1532 Provide as much detail as you can in the body of the commit message. 1632 </para></listitem>
1533 </para></listitem> 1633 <listitem><para>
1534 <listitem><para> 1634 For the body of the commit message, provide detailed
1535 If the change addresses a specific bug or issue that is 1635 information that describes what you changed, why you made
1536 associated with a bug-tracking ID, include a reference to that 1636 the change, and the approach you used.
1537 ID in your detailed description. 1637 It might also be helpful if you mention how you tested
1538 For example, the Yocto Project uses a specific convention for 1638 the change.
1539 bug references - any commit that addresses a specific bug should 1639 Provide as much detail as you can in the body of the
1540 use the following form for the detailed description: 1640 commit message.
1541 <literallayout class='monospaced'> 1641 </para></listitem>
1642 <listitem><para>
1643 If the change addresses a specific bug or issue that is
1644 associated with a bug-tracking ID, include a reference
1645 to that ID in your detailed description.
1646 For example, the Yocto Project uses a specific convention
1647 for bug references - any commit that addresses a specific
1648 bug should use the following form for the detailed
1649 description:
1650 <literallayout class='monospaced'>
1542 Fixes [YOCTO #<replaceable>bug-id</replaceable>] 1651 Fixes [YOCTO #<replaceable>bug-id</replaceable>]
1543 1652
1544 <replaceable>detailed description of change</replaceable> 1653 <replaceable>detailed description of change</replaceable>
1545 </literallayout></para></listitem> 1654 </literallayout>
1655 </para></listitem>
1546 Where <replaceable>bug-id</replaceable> is replaced with the 1656 Where <replaceable>bug-id</replaceable> is replaced with the
1547 specific bug ID from the Yocto Project Bugzilla instance. 1657 specific bug ID from the Yocto Project Bugzilla instance.
1548 </itemizedlist> 1658 </itemizedlist>
1549 </para> 1659 </para>
1550
1551 <para>
1552 You can find more guidance on creating well-formed commit messages at this OpenEmbedded
1553 wiki page:
1554 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
1555 </para>
1556 1660
1557 <para> 1661 <para>
1558 The next two sections describe general instructions for both pushing 1662 You can find more guidance on creating well-formed commit messages
1559 changes upstream and for submitting changes as patches. 1663 at this OpenEmbedded wiki page:
1560 </para> 1664 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
1665 </para>
1666 </section>
1561 1667
1562 <section id='pushing-a-change-upstream'> 1668 <section id='pushing-a-change-upstream'>
1563 <title>Using Scripts to Push a Change Upstream and Request a Pull</title> 1669 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>