How to submit a patch to OpenEmbedded
OpenEmbedded welcomes contributions. Before submitting a patch however there are a few things to keep in mind.
- 1 Finding the right place for your patch
- 2 A task-oriented guide to creating a patch
- 3 Community review
- 4 Appendix
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.
New recipes in particular should be added to the appropriate layer. See the layer index for the list of public layers. If your new recipe doesn't seem to fit anywhere it can be added to the meta-oe layer in the meta-openembedded repository, although if it is likely to be followed by numbers of similar recipes then you may wish to consider creating a new 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 email@example.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 "firstname.lastname@example.org"
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 email@example.com
You can use the --envelope-sender option to have the email appear from the address you are subscribed to the list with. You will need to use the Accounts and import tab under the gmail settings tab. Use the Send mail as 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 firstname.lastname@example.org and for patches against meta-oe and many other layers the list is email@example.com. 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.
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 --firstname.lastname@example.org --confirm=always -M -1
For multiple commits you can substitute -1 above with -N (where N is the number of commits) or instead specify a revision before which to start e.g. HEAD~3, master etc.
Note: in either case if you are submitting a patch for meta-oe or any layer other than OE-Core, please add the appopriate prefix so that it is clear which layer the patch is intended to be applied to:
Please substitute "PATCH" with "PATCH v2" if you are submitting a revised version after addressing feedback (or v3, v4 etc.)
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)
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.
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.