summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml627
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml627
-rw-r--r--documentation/dev-manual/dev-manual.xml2
-rw-r--r--documentation/mega-manual/mega-manual.xml2
4 files changed, 627 insertions, 631 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 9e8dd5fa92..fe1bfba6cf 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -13783,6 +13783,633 @@
13783 </section> 13783 </section>
13784 </section> 13784 </section>
13785 13785
13786 <section id='making-changes-to-the-yocto-project'>
13787 <title>Making Changes to the Yocto Project</title>
13788
13789 <para>
13790 Because the Yocto Project is an open-source, community-based
13791 project, you can effect changes to the project.
13792 This section presents procedures that show you how to submit
13793 a defect against the project and how to submit a change.
13794 </para>
13795
13796 <section id='submitting-a-defect-against-the-yocto-project'>
13797 <title>Submitting a Defect Against the Yocto Project</title>
13798
13799 <para>
13800 Use the Yocto Project implementation of
13801 <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
13802 to submit a defect (bug) against the Yocto Project.
13803 For additional information on this implementation of Bugzilla see the
13804 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
13805 section in the Yocto Project Reference Manual.
13806 For more detail on any of the following steps, see the Yocto Project
13807 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
13808 </para>
13809
13810 <para>
13811 Use the following general steps to submit a bug"
13812
13813 <orderedlist>
13814 <listitem><para>
13815 Open the Yocto Project implementation of
13816 <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
13817 </para></listitem>
13818 <listitem><para>
13819 Click "File a Bug" to enter a new bug.
13820 </para></listitem>
13821 <listitem><para>
13822 Choose the appropriate "Classification", "Product", and
13823 "Component" for which the bug was found.
13824 Bugs for the Yocto Project fall into one of several
13825 classifications, which in turn break down into several
13826 products and components.
13827 For example, for a bug against the
13828 <filename>meta-intel</filename> layer, you would choose
13829 "Build System, Metadata &amp; Runtime", "BSPs", and
13830 "bsps-meta-intel", respectively.
13831 </para></listitem>
13832 <listitem><para>
13833 Choose the "Version" of the Yocto Project for which you found
13834 the bug (e.g. &DISTRO;).
13835 </para></listitem>
13836 <listitem><para>
13837 Determine and select the "Severity" of the bug.
13838 The severity indicates how the bug impacted your work.
13839 </para></listitem>
13840 <listitem><para>
13841 Choose the "Hardware" that the bug impacts.
13842 </para></listitem>
13843 <listitem><para>
13844 Choose the "Architecture" that the bug impacts.
13845 </para></listitem>
13846 <listitem><para>
13847 Choose a "Documentation change" item for the bug.
13848 Fixing a bug might or might not affect the Yocto Project
13849 documentation.
13850 If you are unsure of the impact to the documentation, select
13851 "Don't Know".
13852 </para></listitem>
13853 <listitem><para>
13854 Provide a brief "Summary" of the bug.
13855 Try to limit your summary to just a line or two and be sure
13856 to capture the essence of the bug.
13857 </para></listitem>
13858 <listitem><para>
13859 Provide a detailed "Description" of the bug.
13860 You should provide as much detail as you can about the context,
13861 behavior, output, and so forth that surrounds the bug.
13862 You can even attach supporting files for output from logs by
13863 using the "Add an attachment" button.
13864 </para></listitem>
13865 <listitem><para>
13866 Click the "Submit Bug" button submit the bug.
13867 A new Bugzilla number is assigned to the bug and the defect
13868 is logged in the bug tracking system.
13869 </para></listitem>
13870 </orderedlist>
13871 Once you file a bug, the bug is processed by the Yocto Project Bug
13872 Triage Team and further details concerning the bug are assigned
13873 (e.g. priority and owner).
13874 You are the "Submitter" of the bug and any further categorization,
13875 progress, or comments on the bug result in Bugzilla sending you an
13876 automated email concerning the particular change or progress to the
13877 bug.
13878 </para>
13879 </section>
13880
13881 <section id='how-to-submit-a-change'>
13882 <title>Submitting a Change to the Yocto Project</title>
13883
13884 <para>
13885 Contributions to the Yocto Project and OpenEmbedded are very welcome.
13886 Because the system is extremely configurable and flexible, we recognize
13887 that developers will want to extend, configure or optimize it for
13888 their specific uses.
13889 </para>
13890
13891 <para>
13892 The Yocto Project uses a mailing list and a patch-based workflow
13893 that is similar to the Linux kernel but contains important
13894 differences.
13895 In general, a mailing list exists through which you can submit
13896 patches.
13897 You should send patches to the appropriate mailing list so that they
13898 can be reviewed and merged by the appropriate maintainer.
13899 The specific mailing list you need to use depends on the
13900 location of the code you are changing.
13901 Each component (e.g. layer) should have a
13902 <filename>README</filename> file that indicates where to send
13903 the changes and which process to follow.
13904 </para>
13905
13906 <para>
13907 You can send the patch to the mailing list using whichever approach
13908 you feel comfortable with to generate the patch.
13909 Once sent, the patch is usually reviewed by the community at large.
13910 If somebody has concerns with the patch, they will usually voice
13911 their concern over the mailing list.
13912 If a patch does not receive any negative reviews, the maintainer of
13913 the affected layer typically takes the patch, tests it, and then
13914 based on successful testing, merges the patch.
13915 </para>
13916
13917 <para id='figuring-out-the-mailing-list-to-use'>
13918 The "poky" repository, which is the Yocto Project's reference build
13919 environment, is a hybrid repository that contains several
13920 individual pieces (e.g. BitBake, Metadata, documentation,
13921 and so forth) built using the combo-layer tool.
13922 The upstream location used for submitting changes varies by
13923 component:
13924 <itemizedlist>
13925 <listitem><para>
13926 <emphasis>Core Metadata:</emphasis>
13927 Send your patch to the
13928 <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
13929 mailing list. For example, a change to anything under
13930 the <filename>meta</filename> or
13931 <filename>scripts</filename> directories should be sent
13932 to this mailing list.
13933 </para></listitem>
13934 <listitem><para>
13935 <emphasis>BitBake:</emphasis>
13936 For changes to BitBake (i.e. anything under the
13937 <filename>bitbake</filename> directory), send your patch
13938 to the
13939 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
13940 mailing list.
13941 </para></listitem>
13942 <listitem><para>
13943 <emphasis>"meta-*" trees:</emphasis>
13944 These trees contain Metadata.
13945 Use the
13946 <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
13947 mailing list.
13948 </para></listitem>
13949 </itemizedlist>
13950 </para>
13951
13952 <para>
13953 For changes to other layers hosted in the Yocto Project source
13954 repositories (i.e. <filename>yoctoproject.org</filename>), tools,
13955 and the Yocto Project documentation, use the
13956 <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
13957 general mailing list.
13958 <note>
13959 Sometimes a layer's documentation specifies to use a
13960 particular mailing list.
13961 If so, use that list.
13962 </note>
13963 For additional recipes that do not fit into the core Metadata, you
13964 should determine which layer the recipe should go into and submit
13965 the change in the manner recommended by the documentation (e.g.
13966 the <filename>README</filename> file) supplied with the layer.
13967 If in doubt, please ask on the Yocto general mailing list or on
13968 the openembedded-devel mailing list.
13969 </para>
13970
13971 <para>
13972 You can also push a change upstream and request a maintainer to
13973 pull the change into the component's upstream repository.
13974 You do this by pushing to a contribution repository that is upstream.
13975 See the
13976 "<ulink url='&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>"
13977 section in the Yocto Project Overview and Concepts Manual for additional
13978 concepts on working in the Yocto Project development environment.
13979 </para>
13980
13981 <para>
13982 Two commonly used testing repositories exist for
13983 OpenEmbedded-Core:
13984 <itemizedlist>
13985 <listitem><para>
13986 <emphasis>"ross/mut" branch:</emphasis>
13987 The "mut" (master-under-test) tree
13988 exists in the <filename>poky-contrib</filename> repository
13989 in the
13990 <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
13991 </para></listitem>
13992 <listitem><para>
13993 <emphasis>"master-next" branch:</emphasis>
13994 This branch is part of the main
13995 "poky" repository in the Yocto Project source repositories.
13996 </para></listitem>
13997 </itemizedlist>
13998 Maintainers use these branches to test submissions prior to merging
13999 patches.
14000 Thus, you can get an idea of the status of a patch based on
14001 whether the patch has been merged into one of these branches.
14002 <note>
14003 This system is imperfect and changes can sometimes get lost in the
14004 flow.
14005 Asking about the status of a patch or change is reasonable if the
14006 change has been idle for a while with no feedback.
14007 The Yocto Project does have plans to use
14008 <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
14009 to track the status of patches and also to automatically preview
14010 patches.
14011 </note>
14012 </para>
14013
14014 <para>
14015 The following sections provide procedures for submitting a change.
14016 </para>
14017
14018 <section id='pushing-a-change-upstream'>
14019 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
14020
14021 <para>
14022 Follow this procedure to push a change to an upstream "contrib"
14023 Git repository:
14024 <note>
14025 You can find general Git information on how to push a change
14026 upstream in the
14027 <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
14028 </note>
14029 <orderedlist>
14030 <listitem><para>
14031 <emphasis>Make Your Changes Locally:</emphasis>
14032 Make your changes in your local Git repository.
14033 You should make small, controlled, isolated changes.
14034 Keeping changes small and isolated aids review,
14035 makes merging/rebasing easier and keeps the change
14036 history clean should anyone need to refer to it in
14037 future.
14038 </para></listitem>
14039 <listitem><para>
14040 <emphasis>Stage Your Changes:</emphasis>
14041 Stage your changes by using the <filename>git add</filename>
14042 command on each file you changed.
14043 </para></listitem>
14044 <listitem><para id='making-sure-you-have-correct-commit-information'>
14045 <emphasis>Commit Your Changes:</emphasis>
14046 Commit the change by using the
14047 <filename>git commit</filename> command.
14048 Make sure your commit information follows standards by
14049 following these accepted conventions:
14050 <itemizedlist>
14051 <listitem><para>
14052 Be sure to include a "Signed-off-by:" line in the
14053 same style as required by the Linux kernel.
14054 Adding this line signifies that you, the submitter,
14055 have agreed to the Developer's Certificate of
14056 Origin 1.1 as follows:
14057 <literallayout class='monospaced'>
14058 Developer's Certificate of Origin 1.1
14059
14060 By making a contribution to this project, I certify that:
14061
14062 (a) The contribution was created in whole or in part by me and I
14063 have the right to submit it under the open source license
14064 indicated in the file; or
14065
14066 (b) The contribution is based upon previous work that, to the best
14067 of my knowledge, is covered under an appropriate open source
14068 license and I have the right under that license to submit that
14069 work with modifications, whether created in whole or in part
14070 by me, under the same open source license (unless I am
14071 permitted to submit under a different license), as indicated
14072 in the file; or
14073
14074 (c) The contribution was provided directly to me by some other
14075 person who certified (a), (b) or (c) and I have not modified
14076 it.
14077
14078 (d) I understand and agree that this project and the contribution
14079 are public and that a record of the contribution (including all
14080 personal information I submit with it, including my sign-off) is
14081 maintained indefinitely and may be redistributed consistent with
14082 this project or the open source license(s) involved.
14083 </literallayout>
14084 </para></listitem>
14085 <listitem><para>
14086 Provide a single-line summary of the change.
14087 and,
14088 if more explanation is needed, provide more
14089 detail in the body of the commit.
14090 This summary is typically viewable in the
14091 "shortlist" of changes.
14092 Thus, providing something short and descriptive
14093 that gives the reader a summary of the change is
14094 useful when viewing a list of many commits.
14095 You should prefix this short description with the
14096 recipe name (if changing a recipe), or else with
14097 the short form path to the file being changed.
14098 </para></listitem>
14099 <listitem><para>
14100 For the body of the commit message, provide
14101 detailed information that describes what you
14102 changed, why you made the change, and the approach
14103 you used.
14104 It might also be helpful if you mention how you
14105 tested the change.
14106 Provide as much detail as you can in the body of
14107 the commit message.
14108 <note>
14109 You do not need to provide a more detailed
14110 explanation of a change if the change is
14111 minor to the point of the single line
14112 summary providing all the information.
14113 </note>
14114 </para></listitem>
14115 <listitem><para>
14116 If the change addresses a specific bug or issue
14117 that is associated with a bug-tracking ID,
14118 include a reference to that ID in your detailed
14119 description.
14120 For example, the Yocto Project uses a specific
14121 convention for bug references - any commit that
14122 addresses a specific bug should use the following
14123 form for the detailed description.
14124 Be sure to use the actual bug-tracking ID from
14125 Bugzilla for
14126 <replaceable>bug-id</replaceable>:
14127 <literallayout class='monospaced'>
14128 Fixes [YOCTO #<replaceable>bug-id</replaceable>]
14129
14130 <replaceable>detailed description of change</replaceable>
14131 </literallayout>
14132 </para></listitem>
14133 </itemizedlist>
14134 </para></listitem>
14135 <listitem><para>
14136 <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
14137 If you have arranged for permissions to push to an
14138 upstream contrib repository, push the change to that
14139 repository:
14140 <literallayout class='monospaced'>
14141 $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
14142 </literallayout>
14143 For example, suppose you have permissions to push into the
14144 upstream <filename>meta-intel-contrib</filename>
14145 repository and you are working in a local branch named
14146 <replaceable>your_name</replaceable><filename>/README</filename>.
14147 The following command pushes your local commits to the
14148 <filename>meta-intel-contrib</filename> upstream
14149 repository and puts the commit in a branch named
14150 <replaceable>your_name</replaceable><filename>/README</filename>:
14151 <literallayout class='monospaced'>
14152 $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
14153 </literallayout>
14154 </para></listitem>
14155 <listitem><para id='push-determine-who-to-notify'>
14156 <emphasis>Determine Who to Notify:</emphasis>
14157 Determine the maintainer or the mailing list
14158 that you need to notify for the change.</para>
14159
14160 <para>Before submitting any change, you need to be sure
14161 who the maintainer is or what mailing list that you need
14162 to notify.
14163 Use either these methods to find out:
14164 <itemizedlist>
14165 <listitem><para>
14166 <emphasis>Maintenance File:</emphasis>
14167 Examine the <filename>maintainers.inc</filename>
14168 file, which is located in the
14169 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
14170 at
14171 <filename>meta/conf/distro/include</filename>,
14172 to see who is responsible for code.
14173 </para></listitem>
14174 <listitem><para>
14175 <emphasis>Search by File:</emphasis>
14176 Using <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>,
14177 you can enter the following command to bring up a
14178 short list of all commits against a specific file:
14179 <literallayout class='monospaced'>
14180 git shortlog -- <replaceable>filename</replaceable>
14181 </literallayout>
14182 Just provide the name of the file for which you
14183 are interested.
14184 The information returned is not ordered by history
14185 but does include a list of everyone who has
14186 committed grouped by name.
14187 From the list, you can see who is responsible for
14188 the bulk of the changes against the file.
14189 </para></listitem>
14190 <listitem><para>
14191 <emphasis>Examine the List of Mailing Lists:</emphasis>
14192 For a list of the Yocto Project and related mailing
14193 lists, see the
14194 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
14195 section in the Yocto Project Reference Manual.
14196 </para></listitem>
14197 </itemizedlist>
14198 </para></listitem>
14199 <listitem><para>
14200 <emphasis>Make a Pull Request:</emphasis>
14201 Notify the maintainer or the mailing list that you have
14202 pushed a change by making a pull request.</para>
14203
14204 <para>The Yocto Project provides two scripts that
14205 conveniently let you generate and send pull requests to the
14206 Yocto Project.
14207 These scripts are <filename>create-pull-request</filename>
14208 and <filename>send-pull-request</filename>.
14209 You can find these scripts in the
14210 <filename>scripts</filename> directory within the
14211 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
14212 (e.g. <filename>~/poky/scripts</filename>).
14213 </para>
14214
14215 <para>Using these scripts correctly formats the requests
14216 without introducing any whitespace or HTML formatting.
14217 The maintainer that receives your patches either directly
14218 or through the mailing list needs to be able to save and
14219 apply them directly from your emails.
14220 Using these scripts is the preferred method for sending
14221 patches.</para>
14222
14223 <para>First, create the pull request.
14224 For example, the following command runs the script,
14225 specifies the upstream repository in the contrib directory
14226 into which you pushed the change, and provides a subject
14227 line in the created patch files:
14228 <literallayout class='monospaced'>
14229 $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
14230 </literallayout>
14231 Running this script forms
14232 <filename>*.patch</filename> files in a folder named
14233 <filename>pull-</filename><replaceable>PID</replaceable>
14234 in the current directory.
14235 One of the patch files is a cover letter.</para>
14236
14237 <para>Before running the
14238 <filename>send-pull-request</filename> script, you must
14239 edit the cover letter patch to insert information about
14240 your change.
14241 After editing the cover letter, send the pull request.
14242 For example, the following command runs the script and
14243 specifies the patch directory and email address.
14244 In this example, the email address is a mailing list:
14245 <literallayout class='monospaced'>
14246 $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
14247 </literallayout>
14248 You need to follow the prompts as the script is
14249 interactive.
14250 <note>
14251 For help on using these scripts, simply provide the
14252 <filename>-h</filename> argument as follows:
14253 <literallayout class='monospaced'>
14254 $ poky/scripts/create-pull-request -h
14255 $ poky/scripts/send-pull-request -h
14256 </literallayout>
14257 </note>
14258 </para></listitem>
14259 </orderedlist>
14260 </para>
14261 </section>
14262
14263 <section id='submitting-a-patch'>
14264 <title>Using Email to Submit a Patch</title>
14265
14266 <para>
14267 You can submit patches without using the
14268 <filename>create-pull-request</filename> and
14269 <filename>send-pull-request</filename> scripts described in the
14270 previous section.
14271 However, keep in mind, the preferred method is to use the scripts.
14272 </para>
14273
14274 <para>
14275 Depending on the components changed, you need to submit the email
14276 to a specific mailing list.
14277 For some guidance on which mailing list to use, see the
14278 <link linkend='figuring-out-the-mailing-list-to-use'>list</link>
14279 at the beginning of this section.
14280 For a description of all the available mailing lists, see the
14281 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
14282 section in the Yocto Project Reference Manual.
14283 </para>
14284
14285 <para>
14286 Here is the general procedure on how to submit a patch through
14287 email without using the scripts:
14288 <orderedlist>
14289 <listitem><para>
14290 <emphasis>Make Your Changes Locally:</emphasis>
14291 Make your changes in your local Git repository.
14292 You should make small, controlled, isolated changes.
14293 Keeping changes small and isolated aids review,
14294 makes merging/rebasing easier and keeps the change
14295 history clean should anyone need to refer to it in
14296 future.
14297 </para></listitem>
14298 <listitem><para>
14299 <emphasis>Stage Your Changes:</emphasis>
14300 Stage your changes by using the <filename>git add</filename>
14301 command on each file you changed.
14302 </para></listitem>
14303 <listitem><para>
14304 <emphasis>Commit Your Changes:</emphasis>
14305 Commit the change by using the
14306 <filename>git commit --signoff</filename> command.
14307 Using the <filename>--signoff</filename> option identifies
14308 you as the person making the change and also satisfies
14309 the Developer's Certificate of Origin (DCO) shown earlier.
14310 </para>
14311
14312 <para>When you form a commit, you must follow certain
14313 standards established by the Yocto Project development
14314 team.
14315 See
14316 <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
14317 in the previous section for information on how to
14318 provide commit information that meets Yocto Project
14319 commit message standards.
14320 </para></listitem>
14321 <listitem><para>
14322 <emphasis>Format the Commit:</emphasis>
14323 Format the commit into an email message.
14324 To format commits, use the
14325 <filename>git format-patch</filename> command.
14326 When you provide the command, you must include a revision
14327 list or a number of patches as part of the command.
14328 For example, either of these two commands takes your most
14329 recent single commit and formats it as an email message in
14330 the current directory:
14331 <literallayout class='monospaced'>
14332 $ git format-patch -1
14333 </literallayout>
14334 or
14335 <literallayout class='monospaced'>
14336 $ git format-patch HEAD~
14337 </literallayout></para>
14338
14339 <para>After the command is run, the current directory
14340 contains a numbered <filename>.patch</filename> file for
14341 the commit.</para>
14342
14343 <para>If you provide several commits as part of the
14344 command, the <filename>git format-patch</filename> command
14345 produces a series of numbered files in the current
14346 directory – one for each commit.
14347 If you have more than one patch, you should also use the
14348 <filename>--cover</filename> option with the command,
14349 which generates a cover letter as the first "patch" in
14350 the series.
14351 You can then edit the cover letter to provide a
14352 description for the series of patches.
14353 For information on the
14354 <filename>git format-patch</filename> command,
14355 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed
14356 using the <filename>man git-format-patch</filename>
14357 command.
14358 <note>
14359 If you are or will be a frequent contributor to the
14360 Yocto Project or to OpenEmbedded, you might consider
14361 requesting a contrib area and the necessary associated
14362 rights.
14363 </note>
14364 </para></listitem>
14365 <listitem><para>
14366 <emphasis>Import the Files Into Your Mail Client:</emphasis>
14367 Import the files into your mail client by using the
14368 <filename>git send-email</filename> command.
14369 <note>
14370 In order to use <filename>git send-email</filename>,
14371 you must have the proper Git packages installed on
14372 your host.
14373 For Ubuntu, Debian, and Fedora the package is
14374 <filename>git-email</filename>.
14375 </note></para>
14376
14377 <para>The <filename>git send-email</filename> command
14378 sends email by using a local or remote Mail Transport Agent
14379 (MTA) such as <filename>msmtp</filename>,
14380 <filename>sendmail</filename>, or through a direct
14381 <filename>smtp</filename> configuration in your Git
14382 <filename>~/.gitconfig</filename> file.
14383 If you are submitting patches through email only, it is
14384 very important that you submit them without any whitespace
14385 or HTML formatting that either you or your mailer
14386 introduces.
14387 The maintainer that receives your patches needs to be able
14388 to save and apply them directly from your emails.
14389 A good way to verify that what you are sending will be
14390 applicable by the maintainer is to do a dry run and send
14391 them to yourself and then save and apply them as the
14392 maintainer would.</para>
14393
14394 <para>The <filename>git send-email</filename> command is
14395 the preferred method for sending your patches using
14396 email since there is no risk of compromising whitespace
14397 in the body of the message, which can occur when you use
14398 your own mail client.
14399 The command also has several options that let you
14400 specify recipients and perform further editing of the
14401 email message.
14402 For information on how to use the
14403 <filename>git send-email</filename> command,
14404 see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
14405 the <filename>man git-send-email</filename> command.
14406 </para></listitem>
14407 </orderedlist>
14408 </para>
14409 </section>
14410 </section>
14411 </section>
14412
13786 <section id='working-with-licenses'> 14413 <section id='working-with-licenses'>
13787 <title>Working With Licenses</title> 14414 <title>Working With Licenses</title>
13788 14415
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
deleted file mode 100644
index 27e1d04761..0000000000
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ /dev/null
@@ -1,627 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='dev-manual-newbie'>
6
7<title>The Yocto Project Open Source Development Environment</title>
8
9<section id='submitting-a-defect-against-the-yocto-project'>
10 <title>Submitting a Defect Against the Yocto Project</title>
11
12 <para>
13 Use the Yocto Project implementation of
14 <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
15 to submit a defect (bug) against the Yocto Project.
16 For additional information on this implementation of Bugzilla see the
17 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
18 section in the Yocto Project Reference Manual.
19 For more detail on any of the following steps, see the Yocto Project
20 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
21 </para>
22
23 <para>
24 Use the following general steps to submit a bug"
25
26 <orderedlist>
27 <listitem><para>
28 Open the Yocto Project implementation of
29 <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
30 </para></listitem>
31 <listitem><para>
32 Click "File a Bug" to enter a new bug.
33 </para></listitem>
34 <listitem><para>
35 Choose the appropriate "Classification", "Product", and
36 "Component" for which the bug was found.
37 Bugs for the Yocto Project fall into one of several
38 classifications, which in turn break down into several
39 products and components.
40 For example, for a bug against the
41 <filename>meta-intel</filename> layer, you would choose
42 "Build System, Metadata &amp; Runtime", "BSPs", and
43 "bsps-meta-intel", respectively.
44 </para></listitem>
45 <listitem><para>
46 Choose the "Version" of the Yocto Project for which you found
47 the bug (e.g. &DISTRO;).
48 </para></listitem>
49 <listitem><para>
50 Determine and select the "Severity" of the bug.
51 The severity indicates how the bug impacted your work.
52 </para></listitem>
53 <listitem><para>
54 Choose the "Hardware" that the bug impacts.
55 </para></listitem>
56 <listitem><para>
57 Choose the "Architecture" that the bug impacts.
58 </para></listitem>
59 <listitem><para>
60 Choose a "Documentation change" item for the bug.
61 Fixing a bug might or might not affect the Yocto Project
62 documentation.
63 If you are unsure of the impact to the documentation, select
64 "Don't Know".
65 </para></listitem>
66 <listitem><para>
67 Provide a brief "Summary" of the bug.
68 Try to limit your summary to just a line or two and be sure
69 to capture the essence of the bug.
70 </para></listitem>
71 <listitem><para>
72 Provide a detailed "Description" of the bug.
73 You should provide as much detail as you can about the context,
74 behavior, output, and so forth that surrounds the bug.
75 You can even attach supporting files for output from logs by
76 using the "Add an attachment" button.
77 </para></listitem>
78 <listitem><para>
79 Click the "Submit Bug" button submit the bug.
80 A new Bugzilla number is assigned to the bug and the defect
81 is logged in the bug tracking system.
82 </para></listitem>
83 </orderedlist>
84 Once you file a bug, the bug is processed by the Yocto Project Bug
85 Triage Team and further details concerning the bug are assigned
86 (e.g. priority and owner).
87 You are the "Submitter" of the bug and any further categorization,
88 progress, or comments on the bug result in Bugzilla sending you an
89 automated email concerning the particular change or progress to the
90 bug.
91 </para>
92</section>
93
94<section id='how-to-submit-a-change'>
95 <title>Submitting a Change to the Yocto Project</title>
96
97 <para>
98 Contributions to the Yocto Project and OpenEmbedded are very welcome.
99 Because the system is extremely configurable and flexible, we recognize
100 that developers will want to extend, configure or optimize it for
101 their specific uses.
102 </para>
103
104 <para>
105 The Yocto Project uses a mailing list and a patch-based workflow
106 that is similar to the Linux kernel but contains important
107 differences.
108 In general, a mailing list exists through which you can submit
109 patches.
110 You should send patches to the appropriate mailing list so that they
111 can be reviewed and merged by the appropriate maintainer.
112 The specific mailing list you need to use depends on the
113 location of the code you are changing.
114 Each component (e.g. layer) should have a
115 <filename>README</filename> file that indicates where to send
116 the changes and which process to follow.
117 </para>
118
119 <para>
120 You can send the patch to the mailing list using whichever approach
121 you feel comfortable with to generate the patch.
122 Once sent, the patch is usually reviewed by the community at large.
123 If somebody has concerns with the patch, they will usually voice
124 their concern over the mailing list.
125 If a patch does not receive any negative reviews, the maintainer of
126 the affected layer typically takes the patch, tests it, and then
127 based on successful testing, merges the patch.
128 </para>
129
130 <para id='figuring-out-the-mailing-list-to-use'>
131 The "poky" repository, which is the Yocto Project's reference build
132 environment, is a hybrid repository that contains several
133 individual pieces (e.g. BitBake, Metadata, documentation,
134 and so forth) built using the combo-layer tool.
135 The upstream location used for submitting changes varies by
136 component:
137 <itemizedlist>
138 <listitem><para>
139 <emphasis>Core Metadata:</emphasis>
140 Send your patch to the
141 <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
142 mailing list. For example, a change to anything under
143 the <filename>meta</filename> or
144 <filename>scripts</filename> directories should be sent
145 to this mailing list.
146 </para></listitem>
147 <listitem><para>
148 <emphasis>BitBake:</emphasis>
149 For changes to BitBake (i.e. anything under the
150 <filename>bitbake</filename> directory), send your patch
151 to the
152 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
153 mailing list.
154 </para></listitem>
155 <listitem><para>
156 <emphasis>"meta-*" trees:</emphasis>
157 These trees contain Metadata.
158 Use the
159 <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
160 mailing list.
161 </para></listitem>
162 </itemizedlist>
163 </para>
164
165 <para>
166 For changes to other layers hosted in the Yocto Project source
167 repositories (i.e. <filename>yoctoproject.org</filename>), tools,
168 and the Yocto Project documentation, use the
169 <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
170 general mailing list.
171 <note>
172 Sometimes a layer's documentation specifies to use a
173 particular mailing list.
174 If so, use that list.
175 </note>
176 For additional recipes that do not fit into the core Metadata, you
177 should determine which layer the recipe should go into and submit
178 the change in the manner recommended by the documentation (e.g.
179 the <filename>README</filename> file) supplied with the layer.
180 If in doubt, please ask on the Yocto general mailing list or on
181 the openembedded-devel mailing list.
182 </para>
183
184 <para>
185 You can also push a change upstream and request a maintainer to
186 pull the change into the component's upstream repository.
187 You do this by pushing to a contribution repository that is upstream.
188 See the
189 "<ulink url='&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>"
190 section in the Yocto Project Overview and Concepts Manual for additional
191 concepts on working in the Yocto Project development environment.
192 </para>
193
194 <para>
195 Two commonly used testing repositories exist for
196 OpenEmbedded-Core:
197 <itemizedlist>
198 <listitem><para>
199 <emphasis>"ross/mut" branch:</emphasis>
200 The "mut" (master-under-test) tree
201 exists in the <filename>poky-contrib</filename> repository
202 in the
203 <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
204 </para></listitem>
205 <listitem><para>
206 <emphasis>"master-next" branch:</emphasis>
207 This branch is part of the main
208 "poky" repository in the Yocto Project source repositories.
209 </para></listitem>
210 </itemizedlist>
211 Maintainers use these branches to test submissions prior to merging
212 patches.
213 Thus, you can get an idea of the status of a patch based on
214 whether the patch has been merged into one of these branches.
215 <note>
216 This system is imperfect and changes can sometimes get lost in the
217 flow.
218 Asking about the status of a patch or change is reasonable if the
219 change has been idle for a while with no feedback.
220 The Yocto Project does have plans to use
221 <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
222 to track the status of patches and also to automatically preview
223 patches.
224 </note>
225 </para>
226
227 <para>
228 The following sections provide procedures for submitting a change.
229 </para>
230
231 <section id='pushing-a-change-upstream'>
232 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
233
234 <para>
235 Follow this procedure to push a change to an upstream "contrib"
236 Git repository:
237 <note>
238 You can find general Git information on how to push a change
239 upstream in the
240 <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
241 </note>
242 <orderedlist>
243 <listitem><para>
244 <emphasis>Make Your Changes Locally:</emphasis>
245 Make your changes in your local Git repository.
246 You should make small, controlled, isolated changes.
247 Keeping changes small and isolated aids review,
248 makes merging/rebasing easier and keeps the change
249 history clean should anyone need to refer to it in
250 future.
251 </para></listitem>
252 <listitem><para>
253 <emphasis>Stage Your Changes:</emphasis>
254 Stage your changes by using the <filename>git add</filename>
255 command on each file you changed.
256 </para></listitem>
257 <listitem><para id='making-sure-you-have-correct-commit-information'>
258 <emphasis>Commit Your Changes:</emphasis>
259 Commit the change by using the
260 <filename>git commit</filename> command.
261 Make sure your commit information follows standards by
262 following these accepted conventions:
263 <itemizedlist>
264 <listitem><para>
265 Be sure to include a "Signed-off-by:" line in the
266 same style as required by the Linux kernel.
267 Adding this line signifies that you, the submitter,
268 have agreed to the Developer's Certificate of
269 Origin 1.1 as follows:
270 <literallayout class='monospaced'>
271 Developer's Certificate of Origin 1.1
272
273 By making a contribution to this project, I certify that:
274
275 (a) The contribution was created in whole or in part by me and I
276 have the right to submit it under the open source license
277 indicated in the file; or
278
279 (b) The contribution is based upon previous work that, to the best
280 of my knowledge, is covered under an appropriate open source
281 license and I have the right under that license to submit that
282 work with modifications, whether created in whole or in part
283 by me, under the same open source license (unless I am
284 permitted to submit under a different license), as indicated
285 in the file; or
286
287 (c) The contribution was provided directly to me by some other
288 person who certified (a), (b) or (c) and I have not modified
289 it.
290
291 (d) I understand and agree that this project and the contribution
292 are public and that a record of the contribution (including all
293 personal information I submit with it, including my sign-off) is
294 maintained indefinitely and may be redistributed consistent with
295 this project or the open source license(s) involved.
296 </literallayout>
297 </para></listitem>
298 <listitem><para>
299 Provide a single-line summary of the change.
300 and,
301 if more explanation is needed, provide more
302 detail in the body of the commit.
303 This summary is typically viewable in the
304 "shortlist" of changes.
305 Thus, providing something short and descriptive
306 that gives the reader a summary of the change is
307 useful when viewing a list of many commits.
308 You should prefix this short description with the
309 recipe name (if changing a recipe), or else with
310 the short form path to the file being changed.
311 </para></listitem>
312 <listitem><para>
313 For the body of the commit message, provide
314 detailed information that describes what you
315 changed, why you made the change, and the approach
316 you used.
317 It might also be helpful if you mention how you
318 tested the change.
319 Provide as much detail as you can in the body of
320 the commit message.
321 <note>
322 You do not need to provide a more detailed
323 explanation of a change if the change is
324 minor to the point of the single line
325 summary providing all the information.
326 </note>
327 </para></listitem>
328 <listitem><para>
329 If the change addresses a specific bug or issue
330 that is associated with a bug-tracking ID,
331 include a reference to that ID in your detailed
332 description.
333 For example, the Yocto Project uses a specific
334 convention for bug references - any commit that
335 addresses a specific bug should use the following
336 form for the detailed description.
337 Be sure to use the actual bug-tracking ID from
338 Bugzilla for
339 <replaceable>bug-id</replaceable>:
340 <literallayout class='monospaced'>
341 Fixes [YOCTO #<replaceable>bug-id</replaceable>]
342
343 <replaceable>detailed description of change</replaceable>
344 </literallayout>
345 </para></listitem>
346 </itemizedlist>
347 </para></listitem>
348 <listitem><para>
349 <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
350 If you have arranged for permissions to push to an
351 upstream contrib repository, push the change to that
352 repository:
353 <literallayout class='monospaced'>
354 $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
355 </literallayout>
356 For example, suppose you have permissions to push into the
357 upstream <filename>meta-intel-contrib</filename>
358 repository and you are working in a local branch named
359 <replaceable>your_name</replaceable><filename>/README</filename>.
360 The following command pushes your local commits to the
361 <filename>meta-intel-contrib</filename> upstream
362 repository and puts the commit in a branch named
363 <replaceable>your_name</replaceable><filename>/README</filename>:
364 <literallayout class='monospaced'>
365 $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
366 </literallayout>
367 </para></listitem>
368 <listitem><para id='push-determine-who-to-notify'>
369 <emphasis>Determine Who to Notify:</emphasis>
370 Determine the maintainer or the mailing list
371 that you need to notify for the change.</para>
372
373 <para>Before submitting any change, you need to be sure
374 who the maintainer is or what mailing list that you need
375 to notify.
376 Use either these methods to find out:
377 <itemizedlist>
378 <listitem><para>
379 <emphasis>Maintenance File:</emphasis>
380 Examine the <filename>maintainers.inc</filename>
381 file, which is located in the
382 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
383 at
384 <filename>meta/conf/distro/include</filename>,
385 to see who is responsible for code.
386 </para></listitem>
387 <listitem><para>
388 <emphasis>Search by File:</emphasis>
389 Using <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>,
390 you can enter the following command to bring up a
391 short list of all commits against a specific file:
392 <literallayout class='monospaced'>
393 git shortlog -- <replaceable>filename</replaceable>
394 </literallayout>
395 Just provide the name of the file for which you
396 are interested.
397 The information returned is not ordered by history
398 but does include a list of everyone who has
399 committed grouped by name.
400 From the list, you can see who is responsible for
401 the bulk of the changes against the file.
402 </para></listitem>
403 <listitem><para>
404 <emphasis>Examine the List of Mailing Lists:</emphasis>
405 For a list of the Yocto Project and related mailing
406 lists, see the
407 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
408 section in the Yocto Project Reference Manual.
409 </para></listitem>
410 </itemizedlist>
411 </para></listitem>
412 <listitem><para>
413 <emphasis>Make a Pull Request:</emphasis>
414 Notify the maintainer or the mailing list that you have
415 pushed a change by making a pull request.</para>
416
417 <para>The Yocto Project provides two scripts that
418 conveniently let you generate and send pull requests to the
419 Yocto Project.
420 These scripts are <filename>create-pull-request</filename>
421 and <filename>send-pull-request</filename>.
422 You can find these scripts in the
423 <filename>scripts</filename> directory within the
424 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
425 (e.g. <filename>~/poky/scripts</filename>).
426 </para>
427
428 <para>Using these scripts correctly formats the requests
429 without introducing any whitespace or HTML formatting.
430 The maintainer that receives your patches either directly
431 or through the mailing list needs to be able to save and
432 apply them directly from your emails.
433 Using these scripts is the preferred method for sending
434 patches.</para>
435
436 <para>First, create the pull request.
437 For example, the following command runs the script,
438 specifies the upstream repository in the contrib directory
439 into which you pushed the change, and provides a subject
440 line in the created patch files:
441 <literallayout class='monospaced'>
442 $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
443 </literallayout>
444 Running this script forms
445 <filename>*.patch</filename> files in a folder named
446 <filename>pull-</filename><replaceable>PID</replaceable>
447 in the current directory.
448 One of the patch files is a cover letter.</para>
449
450 <para>Before running the
451 <filename>send-pull-request</filename> script, you must
452 edit the cover letter patch to insert information about
453 your change.
454 After editing the cover letter, send the pull request.
455 For example, the following command runs the script and
456 specifies the patch directory and email address.
457 In this example, the email address is a mailing list:
458 <literallayout class='monospaced'>
459 $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
460 </literallayout>
461 You need to follow the prompts as the script is
462 interactive.
463 <note>
464 For help on using these scripts, simply provide the
465 <filename>-h</filename> argument as follows:
466 <literallayout class='monospaced'>
467 $ poky/scripts/create-pull-request -h
468 $ poky/scripts/send-pull-request -h
469 </literallayout>
470 </note>
471 </para></listitem>
472 </orderedlist>
473 </para>
474 </section>
475
476 <section id='submitting-a-patch'>
477 <title>Using Email to Submit a Patch</title>
478
479 <para>
480 You can submit patches without using the
481 <filename>create-pull-request</filename> and
482 <filename>send-pull-request</filename> scripts described in the
483 previous section.
484 However, keep in mind, the preferred method is to use the scripts.
485 </para>
486
487 <para>
488 Depending on the components changed, you need to submit the email
489 to a specific mailing list.
490 For some guidance on which mailing list to use, see the
491 <link linkend='figuring-out-the-mailing-list-to-use'>list</link>
492 at the beginning of this section.
493 For a description of all the available mailing lists, see the
494 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
495 section in the Yocto Project Reference Manual.
496 </para>
497
498 <para>
499 Here is the general procedure on how to submit a patch through
500 email without using the scripts:
501 <orderedlist>
502 <listitem><para>
503 <emphasis>Make Your Changes Locally:</emphasis>
504 Make your changes in your local Git repository.
505 You should make small, controlled, isolated changes.
506 Keeping changes small and isolated aids review,
507 makes merging/rebasing easier and keeps the change
508 history clean should anyone need to refer to it in
509 future.
510 </para></listitem>
511 <listitem><para>
512 <emphasis>Stage Your Changes:</emphasis>
513 Stage your changes by using the <filename>git add</filename>
514 command on each file you changed.
515 </para></listitem>
516 <listitem><para>
517 <emphasis>Commit Your Changes:</emphasis>
518 Commit the change by using the
519 <filename>git commit --signoff</filename> command.
520 Using the <filename>--signoff</filename> option identifies
521 you as the person making the change and also satisfies
522 the Developer's Certificate of Origin (DCO) shown earlier.
523 </para>
524
525 <para>When you form a commit, you must follow certain
526 standards established by the Yocto Project development
527 team.
528 See
529 <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
530 in the previous section for information on how to
531 provide commit information that meets Yocto Project
532 commit message standards.
533 </para></listitem>
534 <listitem><para>
535 <emphasis>Format the Commit:</emphasis>
536 Format the commit into an email message.
537 To format commits, use the
538 <filename>git format-patch</filename> command.
539 When you provide the command, you must include a revision
540 list or a number of patches as part of the command.
541 For example, either of these two commands takes your most
542 recent single commit and formats it as an email message in
543 the current directory:
544 <literallayout class='monospaced'>
545 $ git format-patch -1
546 </literallayout>
547 or
548 <literallayout class='monospaced'>
549 $ git format-patch HEAD~
550 </literallayout></para>
551
552 <para>After the command is run, the current directory
553 contains a numbered <filename>.patch</filename> file for
554 the commit.</para>
555
556 <para>If you provide several commits as part of the
557 command, the <filename>git format-patch</filename> command
558 produces a series of numbered files in the current
559 directory – one for each commit.
560 If you have more than one patch, you should also use the
561 <filename>--cover</filename> option with the command,
562 which generates a cover letter as the first "patch" in
563 the series.
564 You can then edit the cover letter to provide a
565 description for the series of patches.
566 For information on the
567 <filename>git format-patch</filename> command,
568 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed
569 using the <filename>man git-format-patch</filename>
570 command.
571 <note>
572 If you are or will be a frequent contributor to the
573 Yocto Project or to OpenEmbedded, you might consider
574 requesting a contrib area and the necessary associated
575 rights.
576 </note>
577 </para></listitem>
578 <listitem><para>
579 <emphasis>Import the Files Into Your Mail Client:</emphasis>
580 Import the files into your mail client by using the
581 <filename>git send-email</filename> command.
582 <note>
583 In order to use <filename>git send-email</filename>,
584 you must have the proper Git packages installed on
585 your host.
586 For Ubuntu, Debian, and Fedora the package is
587 <filename>git-email</filename>.
588 </note></para>
589
590 <para>The <filename>git send-email</filename> command
591 sends email by using a local or remote Mail Transport Agent
592 (MTA) such as <filename>msmtp</filename>,
593 <filename>sendmail</filename>, or through a direct
594 <filename>smtp</filename> configuration in your Git
595 <filename>~/.gitconfig</filename> file.
596 If you are submitting patches through email only, it is
597 very important that you submit them without any whitespace
598 or HTML formatting that either you or your mailer
599 introduces.
600 The maintainer that receives your patches needs to be able
601 to save and apply them directly from your emails.
602 A good way to verify that what you are sending will be
603 applicable by the maintainer is to do a dry run and send
604 them to yourself and then save and apply them as the
605 maintainer would.</para>
606
607 <para>The <filename>git send-email</filename> command is
608 the preferred method for sending your patches using
609 email since there is no risk of compromising whitespace
610 in the body of the message, which can occur when you use
611 your own mail client.
612 The command also has several options that let you
613 specify recipients and perform further editing of the
614 email message.
615 For information on how to use the
616 <filename>git send-email</filename> command,
617 see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
618 the <filename>man git-send-email</filename> command.
619 </para></listitem>
620 </orderedlist>
621 </para>
622 </section>
623</section>
624</chapter>
625<!--
626vim: expandtab tw=80 ts=4
627-->
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index 18cdb23e7c..93a615c2aa 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -168,8 +168,6 @@
168 168
169 <xi:include href="dev-manual-start.xml"/> 169 <xi:include href="dev-manual-start.xml"/>
170 170
171 <xi:include href="dev-manual-newbie.xml"/>
172
173 <xi:include href="dev-manual-common-tasks.xml"/> 171 <xi:include href="dev-manual-common-tasks.xml"/>
174 172
175 <xi:include href="dev-manual-qemu.xml"/> 173 <xi:include href="dev-manual-qemu.xml"/>
diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml
index ff7242347c..2c0943e261 100644
--- a/documentation/mega-manual/mega-manual.xml
+++ b/documentation/mega-manual/mega-manual.xml
@@ -170,8 +170,6 @@
170 <xi:include 170 <xi:include
171 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/> 171 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/>
172 <xi:include 172 <xi:include
173 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/>
174 <xi:include
175 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/> 173 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/>
176 <xi:include 174 <xi:include
177 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-qemu.xml"/> 175 xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-qemu.xml"/>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-09 11:56:50 +0000