From 368474d7409fd5ae8f8cf8aa08dd0c4d14a4f575 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 --- documentation/dev-manual/dev-manual-newbie.xml | 627 ------------------------- 1 file changed, 627 deletions(-) delete mode 100644 documentation/dev-manual/dev-manual-newbie.xml (limited to 'documentation/dev-manual/dev-manual-newbie.xml') 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. - - - -
-
- - -- cgit v1.2.3-54-g00ecf