1. 1 February 6, 2008 1 Patches William Cohen NCSU CSC 591W February 6, 2008

2. 2 2 Why Patches? ● Relatively compact compared to the original software ● Why send 40MB tarball for one line change? ● Focus people attention on the modification ● Possible to apply patches despite file changes ● Many revision control system generate patches easily ● Many tools available for dealing with patches

3. 3 February 6, 2008 3 What is a “Patch”? ● A file that describes the changes in the files or files in a directory ● Usually applied to source code, but could have patch files so show changes to any text file

4. 4 February 6, 2008 4 Example Patch --- opcontrol2003-06-05 14:12:37.000000000 -0500 ● +++ oprofile-0.5.3/utils/opcontrol2003-05-25 20:28:51.000000000 - 0500 ● @@ -229,7 +229,7 @@ ● IS_TIMER=1 ● ;; ● 3|10|i386/athlon|x86-64*) ● -DEFAULT_EVENT=CPU_CLK_UNHALTED ● +DEFAULT_EVENT=RETIRED_INSNS ● ;; ● 6|11|i386/p4*) ● DEFAULT_EVENT=GLOBAL_POWER_EVENTS

5. 5 February 6, 2008 5 Applying Patch ● Unix patch command ● -p n (--strip=n) option to strip off n levels of path ● -b (--backup) save backups of patched files ● -R (--reverse) to reverse sense of patch ● Patch does not blindly apply changes ● Patch uses lines to get context of patch ● Section of patch may apply earlier or later than lines mentioned ● Patch may attempt to use less of context (fuzz factor 1 or 2) ● Section of patch may be rejected unable to find place to install: ● Prints message patch hunk failed ● Creates.rej files with unaccepted sections of patch

6. 6 February 6, 2008 6 Patch Generation and Submission Process ● Start with unmodified version of code ● Add feature or fix bug in code ● Generate patch ● Patch Self Review: ● Look over patch ● Applies to current checkout of software ● Software builds ● Patch works in the expected manner ● Legal ● Patch peer review ● Revise patch, incorporate comments from reviews ● Check patch into code repository

7. 7 February 6, 2008 7 Code ● Usually start with a current version of the code checked out ● May need other patches not currently in the code repository ● May need to update code from repository: ● Development work may take a while ● Other developers may check in changes ● Sometimes useful to have branch in source revision control system: ● Used for larger more complicated patches ● Eliminates checkin from others ● Allows others developers see proposed changes

8. 8 February 6, 2008 8 Code Style Guidelines ● Many projects have code style for consistency: ● GNU coding standards ● linux/Documentation/CodingStyle ● oprofile/doc/CodingStyle ● Indicates how to format code: ● Indentation and space ● Line length ● What should be in include files ● Automated checkers to check simple things

9. 9 February 6, 2008 9 Generating Patch ● Include new files ● Exclude machine generated files ● Possible approaches of generation: ● Unix diff command between files/directories ● Use revision control system

10. 10 February 6, 2008 10 Patch Self Review ● Review patch yourself before having other people review ● Follow code style guidelines for project ● Read over the patch: ● Does it have all the expected changes? ● Does it have unexpected changes? ● Verify that the patch cleanly applies to the current code ● Some projects have frequent changes ● Conflicts may occur ● Check that the patched software builds ● Testing: ● Does the patch cause any regression? ● Does the patch fix some failures?

11. 11 February 6, 2008 11 Patch Submission Checklists ● Some steps may not be obvious to new developers ● Some projects have lists of steps to catch problems before the patch is merged in: ● linux/Documentation/SubmitChecklist ● http://gcc.gnu.org/contribute.html http://gcc.gnu.org/contribute.html

12. 12 February 6, 2008 12 Patchutils ● Patchutils Linux tools to examine and manipulate patches ● Scripts to simplify some common tasks ● Commands include: ● lsdiff, list files modified in patch ● splitdiff, break patch into smaller patches ● rediff, to fix offsets and counts of hand-edited diff

13. 13 February 6, 2008 13 Legal ● If the changes from another project: ● Is the code covered by copyright? ● Is this an acceptable use of the code? ● Are the project licenses compatible? ● If you wrote the code: ● Does the project require copyright assignment? ● Do you have correct copyright notices in code?

14. 14 February 6, 2008 14 Patch Peer Review ● Give other people opportunity to comment about work ● Usually performed on project mailing list ● Other developers may have insights that improve the patch: ● Point out cases that the patch does not address ● Suggest simpler/cleaner methods of implementation ● Peers verify the patch implement desired bug fix or feature

15. 15 February 6, 2008 15 Revising Patch ● Peers may suggest changes to address issues with patch: ● These may be very trivial formatting or naming issues ● May be more substantial changes to address issues ● Peer review may comment on things that need to be addressed, but not solutions to implement them ● Person submitting the patch needs to revise patch to address comments received ● Stick to technical discussion ● Ask for clarification when needed ● Conflicting opinions: ● From different reviewers ● From same reviewer at different times

16. 16 February 6, 2008 16 Checking in Patches ● Someone with commit privileges needs to commit patch: ● Could be you ● Could be maintainer for that area of code ● Changes from patch being checked in: ● Code repository moving target ● Update working set to represent current code with patches ● Check in

17. 17 February 6, 2008 17 Suggestions for Patches ● Read and understand any project guidelines and procedures for patch submission ● Focused patch: ● Have the patch address one issue ● Avoid having unrelated things in patch ● Keep patch small ● Make it easier for people to review (and more likely to review)

18. 18 February 6, 2008 18 Suggestions for Patches (continued) ● Break large patch into series of smaller patches: ● Incremental changes toward larger goal: ● First patches should be applicable by itself ● Following patches can be dependent on earlier patches ● Group changes logically: ● For example: arch independent code in one patch, then patch for each architecture ● Test patch before submitting

19. 19 February 6, 2008 19 Problem Patches ● Patches that have many unrelated changes in them ● Patches that are huge, e.g. 100'sKB in size ● Patches that change things that are unrelated to the patch ● Patches ignore the project coding standards

20. 20 February 6, 2008 20 Further Reading ● http://www.kegel.com/academy/opensource.html http://www.kegel.com/academy/opensource.html ● http://www.oss-watch.ac.uk/resources/softwarepatch.xml http://www.oss-watch.ac.uk/resources/softwarepatch.xml ● http://www.groklaw.net/article.php?story=20041122035814276 http://www.groklaw.net/article.php?story=20041122035814276