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

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 February 6, 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 February 6, Example Patch --- opcontrol :12: ● +++ oprofile-0.5.3/utils/opcontrol :28: ● -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 February 6, 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 February 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 February 6, 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 February 6, 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 February 6, Generating Patch ● Include new files ● Exclude machine generated files ● Possible approaches of generation: ● Unix diff command between files/directories ● Use revision control system

10 February 6, 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 February 6, 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 ●

12 February 6, 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 February 6, 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 February 6, 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 February 6, 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 February 6, 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 February 6, 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 February 6, 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 February 6, 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 February 6, Further Reading ● ● ●