diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2017-01-18 10:45:28 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-01-20 11:57:25 +0000 |
commit | faee9d8c37c6458af1d093640d2524c1f76f86b0 (patch) | |
tree | 1640736106db9059385a6bfbba5eb464306916d0 | |
parent | f4b667cfbc2145679af940fc39e4df20d6821cd2 (diff) | |
download | poky-faee9d8c37c6458af1d093640d2524c1f76f86b0.tar.gz |
dev-manual: Updated the "How to Submit a Change" section.
Fixes [YOCTO #10905]
I updated the section with suggested improvements for completeness.
The section has been broken into more subsections and provides the
reader with more direction on mailing lists based on components
changed.
(From yocto-docs rev: f7c9010c14d96c64d00ca32e2e217d2dd1343919)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 362 |
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> |