Please note that User Registration has been temporarily disabled due to a recent increase in automated registrations. If anyone needs an account, please request one here: RequestAccount. Thanks for your patience!

Difference between revisions of "How to submit a patch to OpenEmbedded"

From Openembedded.org
Jump to: navigation, search
(Update this page to reflect current state of affairs (still needs a bit more work))
Line 1: Line 1:
{{Outdated}}
+
OpenEmbedded welcomes contributions. Before submitting a patch however there are a few things to keep in mind.
  
== A task-oriented guide to creating a patch ==
+
== Finding the right place for your patch ==
  
'''Note''': More details are available on the policy pages, but this document is good enough for most beginners.
+
OpenEmbedded is now split up into separate layers: OpenEmbedded-Core (OE-Core) which is a small set of core recipes, and other layers for recipes beyond that. For most layers, patches are sent to a mailing list for review before being merged. Further information specific to the layer you're working on please see the README file in the layer.
  
* [[Patchwork]]
+
== A task-oriented guide to creating a patch ==
* [[Commit Policy]]
+
  
Let's say you [[How to create a bitbake recipe for dummies|create a new bitbake recipe for OpenEmbedded]] and you'd like to submit it for inclusion (and you've already tested that it works, of course).
+
Let's say you have made a fix to a recipe, you've tested that it works and you'd like to submit it for merging.
  
 
=== Set up git ===
 
=== Set up git ===
Line 14: Line 13:
 
Properly configuring git (using tekkub@gmail.com as an example user)
 
Properly configuring git (using tekkub@gmail.com as an example user)
  
On Debain / Ubuntu (Note: Fedora uses `yum` OpenSuse uses zypper or yast)
+
On Debian / Ubuntu (Note: Fedora uses `yum` OpenSuse uses zypper or yast)
  
 
  sudo aptitude install git-core git-email
 
  sudo aptitude install git-core git-email
Line 32: Line 31:
 
You can use the --envelope-sender option to have the email appear to from the address you are subscribed to the list. You will need to use the Accounts and import tab ender the gmail settings tab. Use the Send mail ass selection to address you want to send email from.
 
You can use the --envelope-sender option to have the email appear to from the address you are subscribed to the list. You will need to use the Accounts and import tab ender the gmail settings tab. Use the Send mail ass selection to address you want to send email from.
  
=== Create and Commit your patch ===
+
=== Subscribe to the mailing list ===
  
1. First you have to subscribe to the mailing-list '''openembedded-devel@lists.openembedded.org''' to be able to post your patch. See [[Mailing lists]]
+
You need to subscribe to the appropriate mailing-list in order to be able to send your patch(es) there; for patches against OE-Core the mailing list is '''openembedded-core@lists.openembedded.org''' and for patches against meta-oe and many other layers the list is '''openembedded-devel@lists.openembedded.org'''. See [[Mailing lists]] for subscription and further details.
  
2. Commit with a concise and descriptive message - one that explains your changes in a way others get a short overview without
+
=== Committing your patch ===
looking at the code.
+
  
  cd org.openembedded.dev/ # or whereever you keep your clone of the repo
+
Commit with a concise and descriptive message - one that explains your changes in a way others get a short overview without looking at the code.
  git add recipes/nodejs/
+
 
 +
  cd oe-core/ # or whereever you keep your clone of the repo
 +
  git add meta/recipes-devtools/flex
 
  git commit -s # don't use the -m option but include my signature
 
  git commit -s # don't use the -m option but include my signature
  
nodejs: added recipe for v0.2.1
+
    flex: backport Debian patches to fix generated code warnings
+
   
* included libev-cross patch which prevents wscript from executing cross-compiled code
+
    The generated parser had warnings regarding signess and return check
* included node-cross patch which forwards DEST_CPU to v8's ARCH
+
    which makes Linux Kernel's perf tool from 3.4 release to fail without
 +
    those patches.
  
3. Create your patch. '''Use -N for N commits''' to be included in the patch. '''Use -s to add a signoff line''' like "Signed-off-by: Tekku B. <tekkub@gmail.com>"
+
All commit messages must include Signed-off-by (-s option to commit as above). For more guidelines on messages please see [[Commit Patch Message Guidelines]].
  
git format-patch --subject-prefix="PATCH" -1 # creating a patch for my only commit
+
=== Sending patches ===
  
If you are submitting a second version also add
+
There are two possible methods for submitting patches. Either one is acceptable; for a series containing a number of patches the pull request method is preferred although not mandatory.
 +
 
 +
==== Sending using git-send-email ====
 +
 
 +
To send just the top commit on your current branch (substitute mailing list address as appropriate):
 +
 
 +
git send-email --to=openembedded-core@lists.openembedded.org --confirm=always -1
 +
 
 +
For multiple commits you can substitute -1 above with -N (where N is the number of commits) or specify a revision before which to start e.g. HEAD~3, master etc.
 +
 
 +
Note: in either case if you are submitting a second version after making changes, please add
 
  --subject-prefix="PATCH v2"
 
  --subject-prefix="PATCH v2"
  
4. Send your patch to patchwork
+
==== Sending via a pull request ====
 +
 
 +
Alternatively, for larger patch series it is preferable to send a pull request. This involves making a local branch on top of the master branch for your changes, pushing this branch to an accessible repository and then using the create-pull-request and send-pull-request scripts to create and send a patch series with a link to the branch for review.
 +
 
 +
Run scripts/create-pull-request and scripts/send-pull-request to get help on how to use these.
 +
 
 +
'''This section needs a little further expansion.''' - [[User:PaulEggleton|PaulEggleton]] 11:06, 7 November 2012 (UTC)
 +
 
 +
== Community review ==
  
git send-email --to=openembedded-devel@lists.openembedded.org 001-nodejs-added-recipe-for-v0.2.1
+
Your patch will be sent to the mailing list and should be immediately visible on http://patches.openembedded.org/
  
Your patch will be immediately visible on http://patches.openembedded.org/
+
If you get feedback in reply to your patch, you should make changes according to the feedback and submit the next version. Please remember to use <code>--subject-prefix="PATCH v2"</code>, v3, v4 etc. to mark the patch iteration.
+
5. Once your patch has been accepted or rejected, create a patchwork account and update the status to "accepted" or "rejected"
+
  
5++. If you get '''soft-rejected (a lot of feedback)''', you should make changes according to the feedback, submit the next version, and update the status of the previous patch to "superseded". Remember to use `--subject-prefix` to mark the patch iteration.
+
If your patch has not had any feedback after a few days it may have been missed or the appropriate reviewers may not currently be around; it is perfectly fine to reply to it yourself with a "ping" / reminder request for feedback.
  
 
== Appendix ==
 
== Appendix ==
  
=== steps for people which don't have smtp access for git ===  
+
=== Steps for people which don't have SMTP access for git ===  
  
Patches should not be set as attachment but inline.
+
Patches should not be sent as attachment but inline.
  
If you do not have smtp access to your email account you have two options:
+
If you do not have SMTP access to your email account you have two options:
  
1. use a different account (e.g. gmail). you can make one especially
+
1. Use a different account (e.g. gmail). you can make one especially for this. Note that the account may differ from the one in signed-off (although that is inconvenient)
for this. Note that the account may differ from the one in signed-off
+
(although that is inconvenient)
+
  
2. just include the patch in the body of your email. Make sure you use
+
2. Just include the patch in the body of your email. Make sure you use an email client that does not touch the message (turn spaces in tabs,
an email client that does not touch the message (turn spaces in tabs,
+
 
wrap lines etc etc).
 
wrap lines etc etc).
  
A good mail client to do so is '''pine''' (or '''alpine''') or '''mutt'''.
+
A good mail client to do so is '''pine''' (or '''alpine''') or '''mutt'''. For more information refer to Documentation/email-clients.txt in linux
For more information refer to Documentation/email-clients.txt in linux
+
 
kernel sources [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/email-clients.txt].
 
kernel sources [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/email-clients.txt].
  
 
[[Category:FAQ]]
 
[[Category:FAQ]]
 
[[Category:User]]
 
[[Category:User]]

Revision as of 11:06, 7 November 2012

OpenEmbedded welcomes contributions. Before submitting a patch however there are a few things to keep in mind.

Contents

Finding the right place for your patch

OpenEmbedded is now split up into separate layers: OpenEmbedded-Core (OE-Core) which is a small set of core recipes, and other layers for recipes beyond that. For most layers, patches are sent to a mailing list for review before being merged. Further information specific to the layer you're working on please see the README file in the layer.

A task-oriented guide to creating a patch

Let's say you have made a fix to a recipe, you've tested that it works and you'd like to submit it for merging.

Set up git

Properly configuring git (using tekkub@gmail.com as an example user)

On Debian / Ubuntu (Note: Fedora uses `yum` OpenSuse uses zypper or yast)

sudo aptitude install git-core git-email

These are important to the commit meta-data

git config --global user.name "Tekkub"
git config --global user.email "tekkub@gmail.com"

Any Google Apps account

git config --global sendemail.smtpserver smtp.gmail.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpuser tekkupl@gmail.com

You can use the --envelope-sender option to have the email appear to from the address you are subscribed to the list. You will need to use the Accounts and import tab ender the gmail settings tab. Use the Send mail ass selection to address you want to send email from.

Subscribe to the mailing list

You need to subscribe to the appropriate mailing-list in order to be able to send your patch(es) there; for patches against OE-Core the mailing list is openembedded-core@lists.openembedded.org and for patches against meta-oe and many other layers the list is openembedded-devel@lists.openembedded.org. See Mailing lists for subscription and further details.

Committing your patch

Commit with a concise and descriptive message - one that explains your changes in a way others get a short overview without looking at the code.

cd oe-core/ # or whereever you keep your clone of the repo
git add meta/recipes-devtools/flex
git commit -s # don't use the -m option but include my signature
   flex: backport Debian patches to fix generated code warnings
   
   The generated parser had warnings regarding signess and return check
   which makes Linux Kernel's perf tool from 3.4 release to fail without
   those patches.

All commit messages must include Signed-off-by (-s option to commit as above). For more guidelines on messages please see Commit Patch Message Guidelines.

Sending patches

There are two possible methods for submitting patches. Either one is acceptable; for a series containing a number of patches the pull request method is preferred although not mandatory.

Sending using git-send-email

To send just the top commit on your current branch (substitute mailing list address as appropriate):

git send-email --to=openembedded-core@lists.openembedded.org --confirm=always -1

For multiple commits you can substitute -1 above with -N (where N is the number of commits) or specify a revision before which to start e.g. HEAD~3, master etc.

Note: in either case if you are submitting a second version after making changes, please add

--subject-prefix="PATCH v2"

Sending via a pull request

Alternatively, for larger patch series it is preferable to send a pull request. This involves making a local branch on top of the master branch for your changes, pushing this branch to an accessible repository and then using the create-pull-request and send-pull-request scripts to create and send a patch series with a link to the branch for review.

Run scripts/create-pull-request and scripts/send-pull-request to get help on how to use these.

This section needs a little further expansion. - PaulEggleton 11:06, 7 November 2012 (UTC)

Community review

Your patch will be sent to the mailing list and should be immediately visible on http://patches.openembedded.org/

If you get feedback in reply to your patch, you should make changes according to the feedback and submit the next version. Please remember to use --subject-prefix="PATCH v2", v3, v4 etc. to mark the patch iteration.

If your patch has not had any feedback after a few days it may have been missed or the appropriate reviewers may not currently be around; it is perfectly fine to reply to it yourself with a "ping" / reminder request for feedback.

Appendix

Steps for people which don't have SMTP access for git

Patches should not be sent as attachment but inline.

If you do not have SMTP access to your email account you have two options:

1. Use a different account (e.g. gmail). you can make one especially for this. Note that the account may differ from the one in signed-off (although that is inconvenient)

2. Just include the patch in the body of your email. Make sure you use an email client that does not touch the message (turn spaces in tabs, wrap lines etc etc).

A good mail client to do so is pine (or alpine) or mutt. For more information refer to Documentation/email-clients.txt in linux kernel sources [1].

Personal tools
Namespaces

Variants
Actions
Navigation
Categories
OE services
Toolbox