diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml index d32ea20b34..25b4282416 100644 --- a/documentation/kernel-manual/kernel-how-to.xml +++ b/documentation/kernel-manual/kernel-how-to.xml @@ -761,40 +761,46 @@ repository.
- Export for External (Upstream) Submission - -If patches are to be sent for external submission, they can be done via a -pull request if the patch series is large or the maintainer prefers to pull -changes. But commonly, patches are sent as email series for easy review and -integration. - - -Before sending patches for review ensure that you understand the -standard of the community in question and follow their best practices. For -example, kernel patches should follow standards such as: - - - - Documentation/SubmittingPatches (in any linux kernel source tree) - - - -The messages used to commit changes are a large part of these standards, so -ensure that the headers for each commit have the required information. If the -initial commits were not properly documented or don't meet those standards -rebasing via git rebase -i offer an opportunity to manipulate the commits and -get them into the required format. Other techniques such as branching and -cherry picking commits are also viable options. - - -Once complete, patches are sent via email to the maintainer(s) or lists that -review and integrate changes. "git send-email" is commonly used to ensure -that patches are properly formatted for easy application and avoid mailer -induced patch damage. - - -An example of dumping patches for external submission follows: - + Exporting Changes for External (Upstream) Submission + + + This section describes how to export changes for external upstream submission. + If the patch series is large or the maintainer prefers to pull + changes, you can submit these changes by using a pull request. + However, it is common to sent patches as an email series. + This method allows easy review and integration of the changes. + + + + Before sending patches for review be sure you understand the + community standards for submitting and documenting changes and follow their best practices. + For example, kernel patches should follow standards such as: + + + + Documentation/SubmittingPatches (in any linux kernel source tree) + + + + + The messages used to commit changes are a large part of these standards. + Consequently, be sure that the headers for each commit have the required information. + If the initial commits were not properly documented or do not meet those standards, + you can re-base by using the "git rebase -i" command to manipulate the commits and + get them into the required format. + Other techniques such as branching and cherry-picking commits are also viable options. + + + + Once you complete the commits, you can generate the email that sends the patches + to the maintainer(s) or lists that review and integrate changes. + The command "git send-email" is commonly used to ensure that patches are properly + formatted for easy application and avoid mailer-induced patch damage. + + + + The following is an example of dumping patches for external submission: + # dump the last 4 commits > git format-patch --thread -n -o ~/rr/ HEAD^^^^ > git send-email --compose --subject '[RFC 0/N] <patch series summary>' \ @@ -802,88 +808,98 @@ An example of dumping patches for external submission follows: --cc list@yoctoproject.org ~/rr # the editor is invoked for the 0/N patch, and when complete the entire # series is sent via email for review - - + +
- Export for Import into Other SCM - -Using any one of the previously discussed techniques, commits can be exported -as patches for import into another SCM. Note however, that if those patches -are manually applied to a secondary tree and then that secondary tree is -checked into the SCM, then it often results in lost information (like commit -logs) and so it is not recommended. - - -Many SCMs can directly import git commits, or can translate git patches to -not lose information. Those facilities are SCM dependent and should be used -whenever possible. - + Exporting Changes for Import into Another SCM + + + When you want to export changes for import into another + Source Code Manager (SCM) you can use any of the previously discussed + techniques. + However, if the patches are manually applied to a secondary tree and then + that tree is checked into the SCM you can lose change information such as + commit logs. + Yocto Project does not recommend this process. + + + + Many SCMs can directly import git commits, or can translate git patches so that + information is not lost. + Those facilities are SCM-dependent and you should use them whenever possible. +
- SCM: Working with the Yocto Project Kernel in Another SCM - -This is not the same as the exporting of patches to another SCM, but instead -is concerned with kernel development that is done completely in another -environment, but built with the Yocto Project build system. In this scenario two -things must happen: - - The delivered Yocto Project kernel must be exported into the second - SCM. - Development must be exported from that secondary SCM into a - format that can be used by the Yocto Project build system. - - + Working with the Yocto Project Kernel in Another SCM + + + This section describes kernel development in another SCM, which is not the same + as exporting changes to another SCM. + For this scenario you use the Yocto Project build system to + develop the kernel in a different SCM. + The following must be true for you to accomplish this: + + The delivered Yocto Project kernel must be exported into the second + SCM. + Development must be exported from that secondary SCM into a + format that can be used by the Yocto Project build system. + + +
- Exporting Delivered Kernel to SCM - -Depending on the SCM it may be possible to export the entire Yocto Project -kernel git repository, branches and all, into a new environment. This is the -preferred method, since it has the most flexibility and potential to maintain -the meta data associated with each commit. - - -When a direct import mechanism is not available, it is still possible to -export a branch (or series of branches) and check them into a new -repository. - - -The following commands illustrate some of the steps that could be used to -import the common_pc-standard kernel into a secondary SCM - + Exporting the Delivered Kernel to the SCM + + + Depending on the SCM it might be possible to export the entire Yocto Project + kernel git repository, branches and all, into a new environment. + This method is preferred because it has the most flexibility and potential to maintain + the meta data associated with each commit. + + + + When a direct import mechanism is not available, it is still possible to + export a branch (or series of branches) and check them into a new repository. + + + + The following commands illustrate some of the steps you could use to + import the common_pc-standard kernel into a secondary SCM: + > git checkout common_pc-standard > cd .. ; echo linux/.git > .cvsignore > cvs import -m "initial import" linux MY_COMPANY start - -The CVS repo could now be relocated and used in a centralized manner. - - -The following commands illustrate how two BSPs could be condensed and merged -into a second SCM: - + + + + + You could now relocate the CVS repository and use it in a centralized manner. + + + + The following commands illustrate how you can condense and merge two BSPs into a second SCM: + > git checkout common_pc-standard > git merge cav_ebt5800-standard # resolve any conflicts and commit them > cd .. ; echo linux/.git > .cvsignore > cvs import -m "initial import" linux MY_COMPANY start - - + +
- Importing Changes for Build - -Once development has reached a suitable point in the second development -environment, changes can either be exported as patches or imported into git -directly (if a conversion/import mechanism is available for the SCM). - - -If changes are exported as patches, they can be placed in a recipe and -automatically applied to the kernel during patching. - + Importing Changes for the Build + + + Once development has reached a suitable point in the second development + environment, you need to export the changes as patches. + To export them place the changes in a recipe and + automatically apply them to the kernel during patching. +