diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.rst')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.rst | 196 |
1 files changed, 99 insertions, 97 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst index 09f20a2bc9..683f5557ec 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.rst +++ b/documentation/dev-manual/dev-manual-common-tasks.rst | |||
@@ -10775,11 +10775,110 @@ Preparing Changes for Submission | |||
10775 | 10775 | ||
10776 | detailed description of change | 10776 | detailed description of change |
10777 | 10777 | ||
10778 | .. _submitting-a-patch: | ||
10779 | |||
10780 | Using Email to Submit a Patch | ||
10781 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
10782 | |||
10783 | Depending on the components changed, you need to submit the email to a | ||
10784 | specific mailing list. For some guidance on which mailing list to use, | ||
10785 | see the `list <#figuring-out-the-mailing-list-to-use>`__ at the | ||
10786 | beginning of this section. For a description of all the available | ||
10787 | mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the | ||
10788 | Yocto Project Reference Manual. | ||
10789 | |||
10790 | Here is the general procedure on how to submit a patch through email | ||
10791 | without using the scripts once the steps in | ||
10792 | :ref:`preparing-changes-for-submissions` have been followed: | ||
10793 | |||
10794 | 1. *Format the Commit:* Format the commit into an email message. To | ||
10795 | format commits, use the ``git format-patch`` command. When you | ||
10796 | provide the command, you must include a revision list or a number of | ||
10797 | patches as part of the command. For example, either of these two | ||
10798 | commands takes your most recent single commit and formats it as an | ||
10799 | email message in the current directory: | ||
10800 | :: | ||
10801 | |||
10802 | $ git format-patch -1 | ||
10803 | |||
10804 | or :: | ||
10805 | |||
10806 | $ git format-patch HEAD~ | ||
10807 | |||
10808 | After the command is run, the current directory contains a numbered | ||
10809 | ``.patch`` file for the commit. | ||
10810 | |||
10811 | If you provide several commits as part of the command, the | ||
10812 | ``git format-patch`` command produces a series of numbered files in | ||
10813 | the current directory – one for each commit. If you have more than | ||
10814 | one patch, you should also use the ``--cover`` option with the | ||
10815 | command, which generates a cover letter as the first "patch" in the | ||
10816 | series. You can then edit the cover letter to provide a description | ||
10817 | for the series of patches. For information on the | ||
10818 | ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed | ||
10819 | using the ``man git-format-patch`` command. | ||
10820 | |||
10821 | .. note:: | ||
10822 | |||
10823 | If you are or will be a frequent contributor to the Yocto Project | ||
10824 | or to OpenEmbedded, you might consider requesting a contrib area | ||
10825 | and the necessary associated rights. | ||
10826 | |||
10827 | 2. *Send the patches via email:* Send the patches to the recipients and | ||
10828 | relevant mailing lists by using the ``git send-email`` command. | ||
10829 | |||
10830 | .. note:: | ||
10831 | |||
10832 | In order to use ``git send-email``, you must have the proper Git packages | ||
10833 | installed on your host. | ||
10834 | For Ubuntu, Debian, and Fedora the package is ``git-email``. | ||
10835 | |||
10836 | The ``git send-email`` command sends email by using a local or remote | ||
10837 | Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or | ||
10838 | through a direct ``smtp`` configuration in your Git ``~/.gitconfig`` | ||
10839 | file. If you are submitting patches through email only, it is very | ||
10840 | important that you submit them without any whitespace or HTML | ||
10841 | formatting that either you or your mailer introduces. The maintainer | ||
10842 | that receives your patches needs to be able to save and apply them | ||
10843 | directly from your emails. A good way to verify that what you are | ||
10844 | sending will be applicable by the maintainer is to do a dry run and | ||
10845 | send them to yourself and then save and apply them as the maintainer | ||
10846 | would. | ||
10847 | |||
10848 | The ``git send-email`` command is the preferred method for sending | ||
10849 | your patches using email since there is no risk of compromising | ||
10850 | whitespace in the body of the message, which can occur when you use | ||
10851 | your own mail client. The command also has several options that let | ||
10852 | you specify recipients and perform further editing of the email | ||
10853 | message. For information on how to use the ``git send-email`` | ||
10854 | command, see ``GIT-SEND-EMAIL(1)`` displayed using the | ||
10855 | ``man git-send-email`` command. | ||
10856 | |||
10857 | The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__ | ||
10858 | to track the status of patches submitted to the various mailing lists and to | ||
10859 | support automated patch testing. Each submitted patch is checked for common | ||
10860 | mistakes and deviations from the expected patch format and submitters are | ||
10861 | notified by patchtest if such mistakes are found. This process helps to | ||
10862 | reduce the burden of patch review on maintainers. | ||
10863 | |||
10864 | .. note:: | ||
10865 | |||
10866 | This system is imperfect and changes can sometimes get lost in the flow. | ||
10867 | Asking about the status of a patch or change is reasonable if the change | ||
10868 | has been idle for a while with no feedback. | ||
10869 | |||
10778 | .. _pushing-a-change-upstream: | 10870 | .. _pushing-a-change-upstream: |
10779 | 10871 | ||
10780 | Using Scripts to Push a Change Upstream and Request a Pull | 10872 | Using Scripts to Push a Change Upstream and Request a Pull |
10781 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 10873 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
10782 | 10874 | ||
10875 | For larger patch series it is preferable to send a pull request which not | ||
10876 | only includes the patch but also a pointer to a branch that can be pulled | ||
10877 | from. This involves making a local branch for your changes, pushing this | ||
10878 | branch to an accessible repository and then using the ``create-pull-request`` | ||
10879 | and ``send-pull-request`` scripts from openembedded-core to create and send a | ||
10880 | patch series with a link to the branch for review. | ||
10881 | |||
10783 | Follow this procedure to push a change to an upstream "contrib" Git | 10882 | Follow this procedure to push a change to an upstream "contrib" Git |
10784 | repository once the steps in :ref:`preparing-changes-for-submissions` have | 10883 | repository once the steps in :ref:`preparing-changes-for-submissions` have |
10785 | been followed: | 10884 | been followed: |
@@ -10885,103 +10984,6 @@ been followed: | |||
10885 | $ poky/scripts/create-pull-request -h | 10984 | $ poky/scripts/create-pull-request -h |
10886 | $ poky/scripts/send-pull-request -h | 10985 | $ poky/scripts/send-pull-request -h |
10887 | 10986 | ||
10888 | |||
10889 | .. _submitting-a-patch: | ||
10890 | |||
10891 | Using Email to Submit a Patch | ||
10892 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
10893 | |||
10894 | You can submit patches without using the ``create-pull-request`` and | ||
10895 | ``send-pull-request`` scripts described in the previous section. | ||
10896 | However, keep in mind, the preferred method is to use the scripts. | ||
10897 | |||
10898 | Depending on the components changed, you need to submit the email to a | ||
10899 | specific mailing list. For some guidance on which mailing list to use, | ||
10900 | see the `list <#figuring-out-the-mailing-list-to-use>`__ at the | ||
10901 | beginning of this section. For a description of all the available | ||
10902 | mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the | ||
10903 | Yocto Project Reference Manual. | ||
10904 | |||
10905 | Here is the general procedure on how to submit a patch through email | ||
10906 | without using the scripts once the steps in | ||
10907 | :ref:`preparing-changes-for-submissions` have been followed: | ||
10908 | |||
10909 | 1. *Format the Commit:* Format the commit into an email message. To | ||
10910 | format commits, use the ``git format-patch`` command. When you | ||
10911 | provide the command, you must include a revision list or a number of | ||
10912 | patches as part of the command. For example, either of these two | ||
10913 | commands takes your most recent single commit and formats it as an | ||
10914 | email message in the current directory: | ||
10915 | :: | ||
10916 | |||
10917 | $ git format-patch -1 | ||
10918 | |||
10919 | or :: | ||
10920 | |||
10921 | $ git format-patch HEAD~ | ||
10922 | |||
10923 | After the command is run, the current directory contains a numbered | ||
10924 | ``.patch`` file for the commit. | ||
10925 | |||
10926 | If you provide several commits as part of the command, the | ||
10927 | ``git format-patch`` command produces a series of numbered files in | ||
10928 | the current directory – one for each commit. If you have more than | ||
10929 | one patch, you should also use the ``--cover`` option with the | ||
10930 | command, which generates a cover letter as the first "patch" in the | ||
10931 | series. You can then edit the cover letter to provide a description | ||
10932 | for the series of patches. For information on the | ||
10933 | ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed | ||
10934 | using the ``man git-format-patch`` command. | ||
10935 | |||
10936 | .. note:: | ||
10937 | |||
10938 | If you are or will be a frequent contributor to the Yocto Project | ||
10939 | or to OpenEmbedded, you might consider requesting a contrib area | ||
10940 | and the necessary associated rights. | ||
10941 | |||
10942 | 2. *Send the patches via email:* Send the patches to the recipients and | ||
10943 | relevant mailing lists by using the ``git send-email`` command. | ||
10944 | |||
10945 | .. note:: | ||
10946 | |||
10947 | In order to use ``git send-email``, you must have the proper Git packages | ||
10948 | installed on your host. | ||
10949 | For Ubuntu, Debian, and Fedora the package is ``git-email``. | ||
10950 | |||
10951 | The ``git send-email`` command sends email by using a local or remote | ||
10952 | Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or | ||
10953 | through a direct ``smtp`` configuration in your Git ``~/.gitconfig`` | ||
10954 | file. If you are submitting patches through email only, it is very | ||
10955 | important that you submit them without any whitespace or HTML | ||
10956 | formatting that either you or your mailer introduces. The maintainer | ||
10957 | that receives your patches needs to be able to save and apply them | ||
10958 | directly from your emails. A good way to verify that what you are | ||
10959 | sending will be applicable by the maintainer is to do a dry run and | ||
10960 | send them to yourself and then save and apply them as the maintainer | ||
10961 | would. | ||
10962 | |||
10963 | The ``git send-email`` command is the preferred method for sending | ||
10964 | your patches using email since there is no risk of compromising | ||
10965 | whitespace in the body of the message, which can occur when you use | ||
10966 | your own mail client. The command also has several options that let | ||
10967 | you specify recipients and perform further editing of the email | ||
10968 | message. For information on how to use the ``git send-email`` | ||
10969 | command, see ``GIT-SEND-EMAIL(1)`` displayed using the | ||
10970 | ``man git-send-email`` command. | ||
10971 | |||
10972 | The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__ | ||
10973 | to track the status of patches submitted to the various mailing lists and to | ||
10974 | support automated patch testing. Each submitted patch is checked for common | ||
10975 | mistakes and deviations from the expected patch format and submitters are | ||
10976 | notified by patchtest if such mistakes are found. This process helps to | ||
10977 | reduce the burden of patch review on maintainers. | ||
10978 | |||
10979 | .. note:: | ||
10980 | |||
10981 | This system is imperfect and changes can sometimes get lost in the flow. | ||
10982 | Asking about the status of a patch or change is reasonable if the change | ||
10983 | has been idle for a while with no feedback. | ||
10984 | |||
10985 | Responding to Patch Review | 10987 | Responding to Patch Review |
10986 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | 10988 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
10987 | 10989 | ||