From 8d011018b0e8b79a36d7c20824aeabf03286f706 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 17 May 2018 09:32:22 -0700 Subject: dev-manual: Removed "newbie" chapter. This chapter only had the stuff about submitting a defect against YP and making a change to YP. I moved that information into the common tasks chapter as it is "how-to" information. Removal of this chapter alse required that the mega-manual.xml file be updated to not include the chapter. (From yocto-docs rev: 4421b1585c21a6f7862525ba972f7e765626066e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 627 +++++++++++++++++++++ documentation/dev-manual/dev-manual-newbie.xml | 627 --------------------- documentation/dev-manual/dev-manual.xml | 2 - 3 files changed, 627 insertions(+), 629 deletions(-) delete mode 100644 documentation/dev-manual/dev-manual-newbie.xml (limited to 'documentation/dev-manual') 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 @@ +
+ Making Changes to the Yocto Project + + + Because the Yocto Project is an open-source, community-based + project, you can effect changes to the project. + This section presents procedures that show you how to submit + a defect against the project and how to submit a change. + + +
+ Submitting a Defect Against the Yocto Project + + + Use the Yocto Project implementation of + Bugzilla + to submit a defect (bug) against the Yocto Project. + For additional information on this implementation of Bugzilla see the + "Yocto Project Bugzilla" + section in the Yocto Project Reference Manual. + For more detail on any of the following steps, see the Yocto Project + Bugzilla wiki page. + + + + Use the following general steps to submit a bug" + + + + Open the Yocto Project implementation of + Bugzilla. + + + Click "File a Bug" to enter a new bug. + + + Choose the appropriate "Classification", "Product", and + "Component" for which the bug was found. + Bugs for the Yocto Project fall into one of several + classifications, which in turn break down into several + products and components. + For example, for a bug against the + meta-intel layer, you would choose + "Build System, Metadata & Runtime", "BSPs", and + "bsps-meta-intel", respectively. + + + Choose the "Version" of the Yocto Project for which you found + the bug (e.g. &DISTRO;). + + + Determine and select the "Severity" of the bug. + The severity indicates how the bug impacted your work. + + + Choose the "Hardware" that the bug impacts. + + + Choose the "Architecture" that the bug impacts. + + + Choose a "Documentation change" item for the bug. + Fixing a bug might or might not affect the Yocto Project + documentation. + If you are unsure of the impact to the documentation, select + "Don't Know". + + + Provide a brief "Summary" of the bug. + Try to limit your summary to just a line or two and be sure + to capture the essence of the bug. + + + Provide a detailed "Description" of the bug. + You should provide as much detail as you can about the context, + behavior, output, and so forth that surrounds the bug. + You can even attach supporting files for output from logs by + using the "Add an attachment" button. + + + Click the "Submit Bug" button submit the bug. + A new Bugzilla number is assigned to the bug and the defect + is logged in the bug tracking system. + + + Once you file a bug, the bug is processed by the Yocto Project Bug + Triage Team and further details concerning the bug are assigned + (e.g. priority and owner). + You are the "Submitter" of the bug and any further categorization, + progress, or comments on the bug result in Bugzilla sending you an + automated email concerning the particular change or progress to the + bug. + +
+ +
+ Submitting a Change to the Yocto Project + + + Contributions to the Yocto Project and OpenEmbedded are very welcome. + Because the system is extremely configurable and flexible, we recognize + that developers will want to extend, configure or optimize it for + their specific uses. + + + + The Yocto Project uses a mailing list and a patch-based workflow + that is similar to the Linux kernel but contains important + differences. + In general, a mailing list exists through which you can submit + patches. + You should send patches to the appropriate mailing list so that they + can be reviewed and merged by the appropriate maintainer. + The specific mailing list you need to use depends on the + location of the code you are changing. + Each component (e.g. layer) should have a + README file that indicates where to send + the changes and which process to follow. + + + + You can send the patch to the mailing list using whichever approach + you feel comfortable with to generate the patch. + Once sent, the patch is usually reviewed by the community at large. + If somebody has concerns with the patch, they will usually voice + their concern over the mailing list. + If a patch does not receive any negative reviews, the maintainer of + the affected layer typically takes the patch, tests it, and then + based on successful testing, merges the patch. + + + + The "poky" repository, which is the Yocto Project's reference build + environment, is a hybrid repository that contains several + individual pieces (e.g. BitBake, Metadata, documentation, + and so forth) built using the combo-layer tool. + The upstream location used for submitting changes varies by + component: + + + Core Metadata: + Send your patch to the + openembedded-core + mailing list. For example, a change to anything under + the meta or + scripts directories should be sent + to this mailing list. + + + BitBake: + For changes to BitBake (i.e. anything under the + bitbake directory), send your patch + to the + bitbake-devel + mailing list. + + + "meta-*" trees: + These trees contain Metadata. + Use the + poky + mailing list. + + + + + + For changes to other layers hosted in the Yocto Project source + repositories (i.e. yoctoproject.org), tools, + and the Yocto Project documentation, use the + Yocto Project + general mailing list. + + Sometimes a layer's documentation specifies to use a + particular mailing list. + If so, use that list. + + For additional recipes that do not fit into the core Metadata, you + should determine which layer the recipe should go into and submit + the change in the manner recommended by the documentation (e.g. + the README file) supplied with the layer. + If in doubt, please ask on the Yocto general mailing list or on + the openembedded-devel mailing list. + + + + You can also push a change upstream and request a maintainer to + pull the change into the component's upstream repository. + You do this by pushing to a contribution repository that is upstream. + See the + "Git Workflows and the Yocto Project" + section in the Yocto Project Overview and Concepts Manual for additional + concepts on working in the Yocto Project development environment. + + + + Two commonly used testing repositories exist for + OpenEmbedded-Core: + + + "ross/mut" branch: + The "mut" (master-under-test) tree + exists in the poky-contrib repository + in the + Yocto Project source repositories. + + + "master-next" branch: + This branch is part of the main + "poky" repository in the Yocto Project source repositories. + + + Maintainers use these branches to test submissions prior to merging + patches. + Thus, you can get an idea of the status of a patch based on + whether the patch has been merged into one of these branches. + + This system is imperfect and changes can sometimes get lost in the + flow. + Asking about the status of a patch or change is reasonable if the + change has been idle for a while with no feedback. + The Yocto Project does have plans to use + Patchwork + to track the status of patches and also to automatically preview + patches. + + + + + The following sections provide procedures for submitting a change. + + +
+ Using Scripts to Push a Change Upstream and Request a Pull + + + Follow this procedure to push a change to an upstream "contrib" + Git repository: + + You can find general Git information on how to push a change + upstream in the + Git Community Book. + + + + Make Your Changes Locally: + Make your changes in your local Git repository. + You should make small, controlled, isolated changes. + Keeping changes small and isolated aids review, + makes merging/rebasing easier and keeps the change + history clean should anyone need to refer to it in + future. + + + Stage Your Changes: + Stage your changes by using the git add + command on each file you changed. + + + Commit Your Changes: + Commit the change by using the + git commit command. + Make sure your commit information follows standards by + following these accepted conventions: + + + Be sure to include a "Signed-off-by:" line in the + same style as required by the Linux kernel. + Adding this line signifies that you, the submitter, + have agreed to the Developer's Certificate of + Origin 1.1 as follows: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + + + + Provide a single-line summary of the change. + and, + if more explanation is needed, provide more + detail in the body of the commit. + This summary is typically viewable in the + "shortlist" of changes. + Thus, providing something short and descriptive + that gives the reader a summary of the change is + useful when viewing a list of many commits. + You should prefix this short description with the + recipe name (if changing a recipe), or else with + the short form path to the file being changed. + + + For the body of the commit message, provide + detailed information that describes what you + changed, why you made the change, and the approach + you used. + It might also be helpful if you mention how you + tested the change. + Provide as much detail as you can in the body of + the commit message. + + You do not need to provide a more detailed + explanation of a change if the change is + minor to the point of the single line + summary providing all the information. + + + + If the change addresses a specific bug or issue + that is associated with a bug-tracking ID, + include a reference to that ID in your detailed + description. + For example, the Yocto Project uses a specific + convention for bug references - any commit that + addresses a specific bug should use the following + form for the detailed description. + Be sure to use the actual bug-tracking ID from + Bugzilla for + bug-id: + + Fixes [YOCTO #bug-id] + + detailed description of change + + + + + + Push Your Commits to a "Contrib" Upstream: + If you have arranged for permissions to push to an + upstream contrib repository, push the change to that + repository: + + $ git push upstream_remote_repo local_branch_name + + For example, suppose you have permissions to push into the + upstream meta-intel-contrib + repository and you are working in a local branch named + your_name/README. + The following command pushes your local commits to the + meta-intel-contrib upstream + repository and puts the commit in a branch named + your_name/README: + + $ git push meta-intel-contrib your_name/README + + + + Determine Who to Notify: + Determine the maintainer or the mailing list + that you need to notify for the change. + + Before submitting any change, you need to be sure + who the maintainer is or what mailing list that you need + to notify. + Use either these methods to find out: + + + Maintenance File: + Examine the maintainers.inc + file, which is located in the + Source Directory + at + meta/conf/distro/include, + to see who is responsible for code. + + + Search by File: + Using Git, + you can enter the following command to bring up a + short list of all commits against a specific file: + + git shortlog -- filename + + Just provide the name of the file for which you + are interested. + The information returned is not ordered by history + but does include a list of everyone who has + committed grouped by name. + From the list, you can see who is responsible for + the bulk of the changes against the file. + + + Examine the List of Mailing Lists: + For a list of the Yocto Project and related mailing + lists, see the + "Mailing lists" + section in the Yocto Project Reference Manual. + + + + + Make a Pull Request: + Notify the maintainer or the mailing list that you have + pushed a change by making a pull request. + + The Yocto Project provides two scripts that + conveniently let you generate and send pull requests to the + Yocto Project. + These scripts are create-pull-request + and send-pull-request. + You can find these scripts in the + scripts directory within the + Source Directory + (e.g. ~/poky/scripts). + + + Using these scripts correctly formats the requests + without introducing any whitespace or HTML formatting. + The maintainer that receives your patches either directly + or through the mailing list needs to be able to save and + apply them directly from your emails. + Using these scripts is the preferred method for sending + patches. + + First, create the pull request. + For example, the following command runs the script, + specifies the upstream repository in the contrib directory + into which you pushed the change, and provides a subject + line in the created patch files: + + $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" + + Running this script forms + *.patch files in a folder named + pull-PID + in the current directory. + One of the patch files is a cover letter. + + Before running the + send-pull-request script, you must + edit the cover letter patch to insert information about + your change. + After editing the cover letter, send the pull request. + For example, the following command runs the script and + specifies the patch directory and email address. + In this example, the email address is a mailing list: + + $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org + + You need to follow the prompts as the script is + interactive. + + For help on using these scripts, simply provide the + -h argument as follows: + + $ poky/scripts/create-pull-request -h + $ poky/scripts/send-pull-request -h + + + + + +
+ +
+ Using Email to Submit a Patch + + + You can submit patches without using the + create-pull-request and + send-pull-request scripts described in the + previous section. + However, keep in mind, the preferred method is to use the scripts. + + + + Depending on the components changed, you need to submit the email + to a specific mailing list. + For some guidance on which mailing list to use, see the + list + at the beginning of this section. + For a description of all the available mailing lists, see the + "Mailing Lists" + section in the Yocto Project Reference Manual. + + + + Here is the general procedure on how to submit a patch through + email without using the scripts: + + + Make Your Changes Locally: + Make your changes in your local Git repository. + You should make small, controlled, isolated changes. + Keeping changes small and isolated aids review, + makes merging/rebasing easier and keeps the change + history clean should anyone need to refer to it in + future. + + + Stage Your Changes: + Stage your changes by using the git add + command on each file you changed. + + + Commit Your Changes: + Commit the change by using the + git commit --signoff command. + Using the --signoff option identifies + you as the person making the change and also satisfies + the Developer's Certificate of Origin (DCO) shown earlier. + + + When you form a commit, you must follow certain + standards established by the Yocto Project development + team. + See + Step 3 + in the previous section for information on how to + provide commit information that meets Yocto Project + commit message standards. + + + Format the Commit: + Format the commit into an email message. + To format commits, use the + git format-patch command. + When you provide the command, you must include a revision + list or a number of patches as part of the command. + For example, either of these two commands takes your most + recent single commit and formats it as an email message in + the current directory: + + $ git format-patch -1 + + or + + $ git format-patch HEAD~ + + + After the command is run, the current directory + contains a numbered .patch file for + the commit. + + If you provide several commits as part of the + command, the git format-patch command + produces a series of numbered files in the current + directory – one for each commit. + If you have more than one patch, you should also use the + --cover option with the command, + which generates a cover letter as the first "patch" in + the series. + You can then edit the cover letter to provide a + description for the series of patches. + For information on the + git format-patch command, + see GIT_FORMAT_PATCH(1) displayed + using the man git-format-patch + command. + + If you are or will be a frequent contributor to the + Yocto Project or to OpenEmbedded, you might consider + requesting a contrib area and the necessary associated + rights. + + + + Import the Files Into Your Mail Client: + Import the files into your mail client by using the + git send-email command. + + In order to use git send-email, + you must have the proper Git packages installed on + your host. + For Ubuntu, Debian, and Fedora the package is + git-email. + + + The git send-email command + sends email by using a local or remote Mail Transport Agent + (MTA) such as msmtp, + sendmail, or through a direct + smtp configuration in your Git + ~/.gitconfig file. + If you are submitting patches through email only, it is + very important that you submit them without any whitespace + or HTML formatting that either you or your mailer + introduces. + The maintainer that receives your patches needs to be able + to save and apply them directly from your emails. + A good way to verify that what you are sending will be + applicable by the maintainer is to do a dry run and send + them to yourself and then save and apply them as the + maintainer would. + + The git send-email command is + the preferred method for sending your patches using + email since there is no risk of compromising whitespace + in the body of the message, which can occur when you use + your own mail client. + The command also has several options that let you + specify recipients and perform further editing of the + email message. + For information on how to use the + git send-email command, + see GIT-SEND-EMAIL(1) displayed using + the man git-send-email command. + + + +
+
+
+
Working With Licenses 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 @@ - %poky; ] > - - - -The Yocto Project Open Source Development Environment - -
- Submitting a Defect Against the Yocto Project - - - Use the Yocto Project implementation of - Bugzilla - to submit a defect (bug) against the Yocto Project. - For additional information on this implementation of Bugzilla see the - "Yocto Project Bugzilla" - section in the Yocto Project Reference Manual. - For more detail on any of the following steps, see the Yocto Project - Bugzilla wiki page. - - - - Use the following general steps to submit a bug" - - - - Open the Yocto Project implementation of - Bugzilla. - - - Click "File a Bug" to enter a new bug. - - - Choose the appropriate "Classification", "Product", and - "Component" for which the bug was found. - Bugs for the Yocto Project fall into one of several - classifications, which in turn break down into several - products and components. - For example, for a bug against the - meta-intel layer, you would choose - "Build System, Metadata & Runtime", "BSPs", and - "bsps-meta-intel", respectively. - - - Choose the "Version" of the Yocto Project for which you found - the bug (e.g. &DISTRO;). - - - Determine and select the "Severity" of the bug. - The severity indicates how the bug impacted your work. - - - Choose the "Hardware" that the bug impacts. - - - Choose the "Architecture" that the bug impacts. - - - Choose a "Documentation change" item for the bug. - Fixing a bug might or might not affect the Yocto Project - documentation. - If you are unsure of the impact to the documentation, select - "Don't Know". - - - Provide a brief "Summary" of the bug. - Try to limit your summary to just a line or two and be sure - to capture the essence of the bug. - - - Provide a detailed "Description" of the bug. - You should provide as much detail as you can about the context, - behavior, output, and so forth that surrounds the bug. - You can even attach supporting files for output from logs by - using the "Add an attachment" button. - - - Click the "Submit Bug" button submit the bug. - A new Bugzilla number is assigned to the bug and the defect - is logged in the bug tracking system. - - - Once you file a bug, the bug is processed by the Yocto Project Bug - Triage Team and further details concerning the bug are assigned - (e.g. priority and owner). - You are the "Submitter" of the bug and any further categorization, - progress, or comments on the bug result in Bugzilla sending you an - automated email concerning the particular change or progress to the - bug. - -
- -
- Submitting a Change to the Yocto Project - - - Contributions to the Yocto Project and OpenEmbedded are very welcome. - Because the system is extremely configurable and flexible, we recognize - that developers will want to extend, configure or optimize it for - their specific uses. - - - - The Yocto Project uses a mailing list and a patch-based workflow - that is similar to the Linux kernel but contains important - differences. - In general, a mailing list exists through which you can submit - patches. - You should send patches to the appropriate mailing list so that they - can be reviewed and merged by the appropriate maintainer. - The specific mailing list you need to use depends on the - location of the code you are changing. - Each component (e.g. layer) should have a - README file that indicates where to send - the changes and which process to follow. - - - - You can send the patch to the mailing list using whichever approach - you feel comfortable with to generate the patch. - Once sent, the patch is usually reviewed by the community at large. - If somebody has concerns with the patch, they will usually voice - their concern over the mailing list. - If a patch does not receive any negative reviews, the maintainer of - the affected layer typically takes the patch, tests it, and then - based on successful testing, merges the patch. - - - - The "poky" repository, which is the Yocto Project's reference build - environment, is a hybrid repository that contains several - individual pieces (e.g. BitBake, Metadata, documentation, - and so forth) built using the combo-layer tool. - The upstream location used for submitting changes varies by - component: - - - Core Metadata: - Send your patch to the - openembedded-core - mailing list. For example, a change to anything under - the meta or - scripts directories should be sent - to this mailing list. - - - BitBake: - For changes to BitBake (i.e. anything under the - bitbake directory), send your patch - to the - bitbake-devel - mailing list. - - - "meta-*" trees: - These trees contain Metadata. - Use the - poky - mailing list. - - - - - - For changes to other layers hosted in the Yocto Project source - repositories (i.e. yoctoproject.org), tools, - and the Yocto Project documentation, use the - Yocto Project - general mailing list. - - Sometimes a layer's documentation specifies to use a - particular mailing list. - If so, use that list. - - For additional recipes that do not fit into the core Metadata, you - should determine which layer the recipe should go into and submit - the change in the manner recommended by the documentation (e.g. - the README file) supplied with the layer. - If in doubt, please ask on the Yocto general mailing list or on - the openembedded-devel mailing list. - - - - You can also push a change upstream and request a maintainer to - pull the change into the component's upstream repository. - You do this by pushing to a contribution repository that is upstream. - See the - "Git Workflows and the Yocto Project" - section in the Yocto Project Overview and Concepts Manual for additional - concepts on working in the Yocto Project development environment. - - - - Two commonly used testing repositories exist for - OpenEmbedded-Core: - - - "ross/mut" branch: - The "mut" (master-under-test) tree - exists in the poky-contrib repository - in the - Yocto Project source repositories. - - - "master-next" branch: - This branch is part of the main - "poky" repository in the Yocto Project source repositories. - - - Maintainers use these branches to test submissions prior to merging - patches. - Thus, you can get an idea of the status of a patch based on - whether the patch has been merged into one of these branches. - - This system is imperfect and changes can sometimes get lost in the - flow. - Asking about the status of a patch or change is reasonable if the - change has been idle for a while with no feedback. - The Yocto Project does have plans to use - Patchwork - to track the status of patches and also to automatically preview - patches. - - - - - The following sections provide procedures for submitting a change. - - -
- Using Scripts to Push a Change Upstream and Request a Pull - - - Follow this procedure to push a change to an upstream "contrib" - Git repository: - - You can find general Git information on how to push a change - upstream in the - Git Community Book. - - - - Make Your Changes Locally: - Make your changes in your local Git repository. - You should make small, controlled, isolated changes. - Keeping changes small and isolated aids review, - makes merging/rebasing easier and keeps the change - history clean should anyone need to refer to it in - future. - - - Stage Your Changes: - Stage your changes by using the git add - command on each file you changed. - - - Commit Your Changes: - Commit the change by using the - git commit command. - Make sure your commit information follows standards by - following these accepted conventions: - - - Be sure to include a "Signed-off-by:" line in the - same style as required by the Linux kernel. - Adding this line signifies that you, the submitter, - have agreed to the Developer's Certificate of - Origin 1.1 as follows: - - Developer's Certificate of Origin 1.1 - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. - - - - Provide a single-line summary of the change. - and, - if more explanation is needed, provide more - detail in the body of the commit. - This summary is typically viewable in the - "shortlist" of changes. - Thus, providing something short and descriptive - that gives the reader a summary of the change is - useful when viewing a list of many commits. - You should prefix this short description with the - recipe name (if changing a recipe), or else with - the short form path to the file being changed. - - - For the body of the commit message, provide - detailed information that describes what you - changed, why you made the change, and the approach - you used. - It might also be helpful if you mention how you - tested the change. - Provide as much detail as you can in the body of - the commit message. - - You do not need to provide a more detailed - explanation of a change if the change is - minor to the point of the single line - summary providing all the information. - - - - If the change addresses a specific bug or issue - that is associated with a bug-tracking ID, - include a reference to that ID in your detailed - description. - For example, the Yocto Project uses a specific - convention for bug references - any commit that - addresses a specific bug should use the following - form for the detailed description. - Be sure to use the actual bug-tracking ID from - Bugzilla for - bug-id: - - Fixes [YOCTO #bug-id] - - detailed description of change - - - - - - Push Your Commits to a "Contrib" Upstream: - If you have arranged for permissions to push to an - upstream contrib repository, push the change to that - repository: - - $ git push upstream_remote_repo local_branch_name - - For example, suppose you have permissions to push into the - upstream meta-intel-contrib - repository and you are working in a local branch named - your_name/README. - The following command pushes your local commits to the - meta-intel-contrib upstream - repository and puts the commit in a branch named - your_name/README: - - $ git push meta-intel-contrib your_name/README - - - - Determine Who to Notify: - Determine the maintainer or the mailing list - that you need to notify for the change. - - Before submitting any change, you need to be sure - who the maintainer is or what mailing list that you need - to notify. - Use either these methods to find out: - - - Maintenance File: - Examine the maintainers.inc - file, which is located in the - Source Directory - at - meta/conf/distro/include, - to see who is responsible for code. - - - Search by File: - Using Git, - you can enter the following command to bring up a - short list of all commits against a specific file: - - git shortlog -- filename - - Just provide the name of the file for which you - are interested. - The information returned is not ordered by history - but does include a list of everyone who has - committed grouped by name. - From the list, you can see who is responsible for - the bulk of the changes against the file. - - - Examine the List of Mailing Lists: - For a list of the Yocto Project and related mailing - lists, see the - "Mailing lists" - section in the Yocto Project Reference Manual. - - - - - Make a Pull Request: - Notify the maintainer or the mailing list that you have - pushed a change by making a pull request. - - The Yocto Project provides two scripts that - conveniently let you generate and send pull requests to the - Yocto Project. - These scripts are create-pull-request - and send-pull-request. - You can find these scripts in the - scripts directory within the - Source Directory - (e.g. ~/poky/scripts). - - - Using these scripts correctly formats the requests - without introducing any whitespace or HTML formatting. - The maintainer that receives your patches either directly - or through the mailing list needs to be able to save and - apply them directly from your emails. - Using these scripts is the preferred method for sending - patches. - - First, create the pull request. - For example, the following command runs the script, - specifies the upstream repository in the contrib directory - into which you pushed the change, and provides a subject - line in the created patch files: - - $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" - - Running this script forms - *.patch files in a folder named - pull-PID - in the current directory. - One of the patch files is a cover letter. - - Before running the - send-pull-request script, you must - edit the cover letter patch to insert information about - your change. - After editing the cover letter, send the pull request. - For example, the following command runs the script and - specifies the patch directory and email address. - In this example, the email address is a mailing list: - - $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org - - You need to follow the prompts as the script is - interactive. - - For help on using these scripts, simply provide the - -h argument as follows: - - $ poky/scripts/create-pull-request -h - $ poky/scripts/send-pull-request -h - - - - - -
- -
- Using Email to Submit a Patch - - - You can submit patches without using the - create-pull-request and - send-pull-request scripts described in the - previous section. - However, keep in mind, the preferred method is to use the scripts. - - - - Depending on the components changed, you need to submit the email - to a specific mailing list. - For some guidance on which mailing list to use, see the - list - at the beginning of this section. - For a description of all the available mailing lists, see the - "Mailing Lists" - section in the Yocto Project Reference Manual. - - - - Here is the general procedure on how to submit a patch through - email without using the scripts: - - - Make Your Changes Locally: - Make your changes in your local Git repository. - You should make small, controlled, isolated changes. - Keeping changes small and isolated aids review, - makes merging/rebasing easier and keeps the change - history clean should anyone need to refer to it in - future. - - - Stage Your Changes: - Stage your changes by using the git add - command on each file you changed. - - - Commit Your Changes: - Commit the change by using the - git commit --signoff command. - Using the --signoff option identifies - you as the person making the change and also satisfies - the Developer's Certificate of Origin (DCO) shown earlier. - - - When you form a commit, you must follow certain - standards established by the Yocto Project development - team. - See - Step 3 - in the previous section for information on how to - provide commit information that meets Yocto Project - commit message standards. - - - Format the Commit: - Format the commit into an email message. - To format commits, use the - git format-patch command. - When you provide the command, you must include a revision - list or a number of patches as part of the command. - For example, either of these two commands takes your most - recent single commit and formats it as an email message in - the current directory: - - $ git format-patch -1 - - or - - $ git format-patch HEAD~ - - - After the command is run, the current directory - contains a numbered .patch file for - the commit. - - If you provide several commits as part of the - command, the git format-patch command - produces a series of numbered files in the current - directory – one for each commit. - If you have more than one patch, you should also use the - --cover option with the command, - which generates a cover letter as the first "patch" in - the series. - You can then edit the cover letter to provide a - description for the series of patches. - For information on the - git format-patch command, - see GIT_FORMAT_PATCH(1) displayed - using the man git-format-patch - command. - - If you are or will be a frequent contributor to the - Yocto Project or to OpenEmbedded, you might consider - requesting a contrib area and the necessary associated - rights. - - - - Import the Files Into Your Mail Client: - Import the files into your mail client by using the - git send-email command. - - In order to use git send-email, - you must have the proper Git packages installed on - your host. - For Ubuntu, Debian, and Fedora the package is - git-email. - - - The git send-email command - sends email by using a local or remote Mail Transport Agent - (MTA) such as msmtp, - sendmail, or through a direct - smtp configuration in your Git - ~/.gitconfig file. - If you are submitting patches through email only, it is - very important that you submit them without any whitespace - or HTML formatting that either you or your mailer - introduces. - The maintainer that receives your patches needs to be able - to save and apply them directly from your emails. - A good way to verify that what you are sending will be - applicable by the maintainer is to do a dry run and send - them to yourself and then save and apply them as the - maintainer would. - - The git send-email command is - the preferred method for sending your patches using - email since there is no risk of compromising whitespace - in the body of the message, which can occur when you use - your own mail client. - The command also has several options that let you - specify recipients and perform further editing of the - email message. - For information on how to use the - git send-email command, - see GIT-SEND-EMAIL(1) displayed using - the man git-send-email command. - - - -
-
- - 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 @@ - - -- cgit v1.2.3-54-g00ecf