Submitting Patches

Thank You

Do you have a bug fix? Do you have a new feature? We welcome your patches, and we thank you for them. This page describes the process for getting bug fixes and patches successfully integrated into LUV.

Lifecycle of a patch

Idea

A patch begins with you, the developer, taking up the challenge of implementing a feature idea, fixing a bug, or simply making the code base better. Then, you, the developer, simply go out and start working on the feature.

Work

To get started, clone the LUV codebase and begin working on your code changes.

Submission

Once you've finished your code change, create one or more patches out of it, and submit it to the mailing list at luv@lists.01.org

Discussion

When your patch arrives on the mailing list, you can expect people test it and/or provide feedback on it. Depending on the nature of your patch(es), one or more rounds of review will be needed. Please respond to feedback comments. Sometimes, even an "OK" or a "got it" is enough. If you disagree with any the feedback given, don't be afraid to speak up! It is OK to disagree.

Some things to consider are implementation, design and maintainability concerns when discussing your patches. Please note that the decision on whether to apply your patch relies solely on the maintainer. Thus, you must address her/his concerns to her/his satisfaction, or successfully plead your case about why he or she is wrong.

Merging

Once the discussion of your patch is complete, the maintainer will take it and apply it into the codebase. You can expect your change to appear first in one or more of the -next branches. LUV maintains a generic next branch that follows the master branch of the Yocto Project. Also, LUV maintains a [YP release]-next branch that follows the a specific branch of the Yocto Project. Your patch will be kept in this branch until it has been thoroughly tested.

Success!

Once your patch has been tested, it will be moved to the master branch and one or more of the LUV branches that match the releases of the Yocto Project.

Checklist to submit patches

This is a short list of "Do" and "Don't" items to consider when writing patches. You can start by reading what Linux, the Yocto Project and OpenEmbedded have to say about this topic. Please go now and read those resources and then come back here. Once you have read above, let's look at the specifics relevant to the LUV Project.

• DO: Split your work into several patches. A patch should be a self-contained logical unit. For instance, a single patch fixes a single bug or implements a single feature. Sometimes, a new feature or bug needs preparatory work. Preparatory work goes in separate patches. For instance, if your code introduces a) a new boot configuration and b) fixes a timeout issue, you should split into two patches.

  There is not a clear-cut methodology on how to correctly separate your changes into several patches. A rule of thumb may be to consider your commit message. If you find yourself writing words like "also", "likewise", "additionally" in your commit message, you may need to consider splitting your work into several patches.

• DO: Test your patches individually. When splitting patches, make sure that each and every patch builds and boots correctly. This is especially useful when we need to bisect code to find issues. Bisection is likely to touch your intermediate patches. If they don't build, the bisection is useless. If you are planning to submit several patches, a cover letter is required. The cover letter gives a high- level overview of your changes and describes why they are exciting/needed. Examples of good cover letters are here and here. You can generate a cover letter by adding the --cover-letter option when you use git format-patch when generating your patches.

• DO: Write informative commit messages. Commit messages are as important as the code changes. Please do invest time writing good commit messages. A good commit message looks like this:

  component: subcomponent: short summary
  
  Here you describe what the problem is with the current implementation and
  how your change fixes the problem. If you are adding a new feature, you
  describe why this feature will benefit the project and why people would
  want it.
  
  If, for some reason, your code cannot be understood by looking at it quickly
  this is the place to explain.
  
  If you are fixing a bug, it would be good to include a link to a bug database.
  
  Signed-off-by: Author Name <author.email@some.domain.com>
  

  Please be as verbose as you can. We are yet to see a too verbose commit message! If you are fixing a bug, refer to the specific bug ID in the commit message. Bug reports are tracked on github. See more info at the end of the page.

• DO: Wrap your line length at 75 characters max!

  Remember to wrap your text at 75 characters. Previously we used 80-char lines; however, since the Linux kernel uses 75-character lines, it is useful for email clients to not wrap lines and make replies to patches look odd.

• DO: Spell-check your commits, following standard English grammar and punctuation rules. You can find examples of good commit message here, here and here.

• DO: Include the signed-off-by line as the last line of your commit message. Make sure you sign your work by including the Signed-off-by line. Rationale of its use here and here.

• DON'T: Please don't break anything! Before submitting patches, test them thoroughly. Make sure your code builds successfully for all of the following:

  • qemux86_64
  • qemux86
  • qemuarch64

  To make this as easy as possible, we suggest maintaining several separate clones for each architecture, or changing your build/local/local.conf file and use the TMPDIR variable to point to different directories for architecture. Make sure that your patches build successfully from clean builds.

• DON'T: Please don't submit patches that generate warnings

  Although a patch may not technically "break" a built, it might generate a warning upon build. Build warnings are not OK. Be sure that your patches do not generate any warnings and do ONLY what you intend them to do. Test them thoroughly, under different architectures if applicable. Test not only the main code path but the error paths as well. Handle errors gracefully.

• DON'T: Don't get complacent regarding input

  If you are taking user input, be defensive. Always check for invalid input, malformed input and malicious input.

The body of your patches

Since the core of your work happens in the body of your patches, you are the best person to judge the quality of it. Here are a few more tips to help you.

• Please follow the indentation convention of the code you are changing. If it uses tabs, use tabs. If curvy brackets starts in a new line, do so you.
• Be on the lookout for trailing spaces; for this git diff is your friend. For example, it is common when developing for the Yocto Project to include patches to be applied locally. Thus, your patches will contain other patches. These will contain some trailing spaces. This is the only case in which trailing spaces are fine.
• Resist the temptation to fix the indentation of a file while you work on it. Focus on your bug or feature and only on it. The diff generated by your patch should contain only your code changes. This eases review and also helps to build a clean and readable change log of the source code. Patches that fix indentation are generally not advisable as they will make difficult following the history of a file when doing things like git blame. If you insist on fixing the indentation, submit a separate patch.
• When adding a new recipe, make sure that it contains all the needed dependencies. More info here and here.

Your patches should apply cleanly

When you submit patches, it is your job to make sure that they apply cleanly on the relevant codebase. Generally, this code base is the next branch. Patches that don't apply cleanly slow everybody down and make it difficult for people to test your changes for you. Patches not applied cleanly also waste a maintainer's cycles.

Revising your patches

Unless you are a deity, it is unlikely that your patches will be perfect the first time. You will likely need to send one or more revised versions of your work. You will receive feedback on your patches. Please do not take feedback personally. Please answer the questions you are asked. Be ready to defend your code, but also be open to feedback. Please agree or disagree on the feedback you receive. It is OK to disagree. If you disagree, defend your code, make your case with technical arguments, discuss pros and cons. If people test your patches, thank them! If you agree, a simple "OK" or "got it" will do the trick.

Once you have submitted your patches, received feedback, and responded to it, you will need to work on a subsequent version. Your patches need to reflect that they are a newer version of a previous submission. Do this by indicating so in the subject line. For example, you can add the --subject-prefix="PATCH VX" option when generating your patches with git format-patch

Where the syntax is ``X`` as the new version of your patch. The second submission will be ``X=2``, and so on.

Also, for your revised versions, please include what changed from V(X-1) to VX. If you are sending this more than one patch, include it in the cover letter. If you are sending a single patch, you can include it in the commit message. In this case, please include the changelog after a line containing three dashes:

[PATCH V2] component: subcomponent: change summary

Fix all the problems in the world by inverting the boot sequence

Signed-off-by: Author Name <author@some.domain.com>

---

Changes since v1:
* Fix variable
* Correct logic

Your change log is useful for people reviewing your patches to know what to look for in your new version. It will be dropped when applying your patches. The three dashes act as scissors cut lines.

In summary

Before submitting your patches, you must:

• Format your patches according to the guidance given here and in the Yocto Project and OpenEmbedded.
• Make sure that your patches build correctly for qemux86_64, qemux86, and qemuarm64.
• Make sure that your patches do not generate any warning(s) when building.
• Test your patches thoroughly. Make sure that they run as intended. Also, do not test only the main code path. Test the error paths too and handle errors gracefully.
• If your code requires interaction from the user, be defensive. Test erroneous input, malformed input, malicious input.
• Make sure you include a Signed-off-by: Your Name <your.email@some.domain.com>
• Run your commit message through spell checker.
• Check your patch for spurious trailing spaces.
• Make sure your patch applies cleanly on the next branch.
• If you are sending a subsequent version of your patch, please use the format PATCH VX; where X is the version of your new submission.
• Include a cover letter when you are submitting more than one patch.
• Follow the indentation convention of the code you are modifying. Also, bear in mind that some pieces of code use tabs and others use spaces.
• Respond to feedback.