patch 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  1. .TH PATCH 1
  2. .SH NAME
  3. patch \- simple patch creation and tracking system
  4. .SH SYNOPSIS
  5. .B patch/create
  6. .I name
  7. .I email
  8. .I files ...
  9. [
  10. .B <
  11. .I description
  12. ]
  13. .PP
  14. .B patch/list
  15. [
  16. .I name ...
  17. ]
  18. .PP
  19. .B patch/diff
  20. .I name
  21. .PP
  22. .B patch/apply
  23. .I name
  24. .PP
  25. .B patch/undo
  26. .I name
  27. .PP
  28. .B patch/note
  29. .I name
  30. [
  31. .B <
  32. .I note
  33. ]
  34. .SH DESCRIPTION
  35. These scripts are a simple patch submission and tracking system
  36. used to propose additions or changes to Plan 9.
  37. Each patch has a
  38. .I name
  39. (lowercase letters, numbers, dash, dot, and underscore only)
  40. and is stored in
  41. .BI /n/sources/patch/ name \fR.
  42. .PP
  43. .I Patch/create
  44. creates a new patch consisting of the changes to
  45. the listed files from the distribution, reading
  46. a description of the patch from standard input:
  47. please provide an explanation of what the change is supposed to do,
  48. some context, and a rationale for the change.
  49. Test data or pointers to same to verify that the fix works are also welcome.
  50. When sending a patch, follow these guidelines:
  51. .IP • 3
  52. Before preparing the patch, run
  53. .I replica/pull
  54. and base your patch on current distribution source code.
  55. .IP •
  56. If this is a bug fix, explain the bug clearly.
  57. Don't assume the bug is obvious from the fix.
  58. .IP •
  59. If this is a new feature, explain it clearly.
  60. Don't assume it is obvious from the change.
  61. .IP •
  62. Make the new code look as much like the old code as possible:
  63. don't make gratuitous changes, and do follow the style of the old code.
  64. See
  65. .IR style (6)
  66. for the canonical Plan 9 coding style.
  67. .IP •
  68. If your patch changes externally-visible behaviour,
  69. update the manual page.
  70. .PP
  71. The
  72. .I email
  73. address, if not
  74. .LR - ,
  75. will be sent notification messages when the patch is applied, rejected,
  76. or commented on.
  77. If rejected, the e-mail will contain a note explaining why and
  78. probably listing suggested changes and encouraging you to resubmit.
  79. .PP
  80. .I Patch/list
  81. displays information about the named patches,
  82. or all currently pending patches if none are specified.
  83. .PP
  84. .I Patch/diff
  85. shows a patch as diffs between the original
  86. source files and the patched source files.
  87. .PP
  88. .I Patch/apply
  89. applies the patch to the current source tree.
  90. It is intended to be run by the Plan 9 developers with
  91. .B yoshimi
  92. as their root file system.
  93. If the source has changed since the patch was
  94. created,
  95. .I apply
  96. will report the conflict and not change any files.
  97. Before changing any files,
  98. .I patch/apply
  99. makes backup copies of the current source tree's
  100. files. The backups are stored in the patch directory.
  101. .PP
  102. .I Patch/undo
  103. will copy the backups saved by
  104. .I patch/apply
  105. back into the source tree.
  106. It will not restore a backup if the file
  107. being replaced is not byte-identical to the one
  108. created by
  109. .I patch/apply.
  110. .SH EXAMPLES
  111. Propose a change to
  112. .IR pwd ,
  113. which you have modified locally:
  114. .IP
  115. .EX
  116. % patch/create pwd-errors user@host.dom /sys/src/cmd/pwd.c
  117. Fix pwd to print errors to fd 2 rather than 1.
  118. ^D
  119. %
  120. .EE
  121. .PP
  122. Then the developers at Bell Labs run
  123. .IP
  124. .EX
  125. patch/diff pwd-errors
  126. .EE
  127. .PP
  128. to inspect the change (possibly viewing
  129. .B /n/sources/patch/pwd-errors/pwd.c
  130. to see the larger context).
  131. To make the change, they run
  132. .IP
  133. .EX
  134. patch/apply pwd-errors
  135. .EE
  136. .LP
  137. Otherwise they run
  138. .IP
  139. .EX
  140. % patch/note pwd-errors
  141. Pwd should definitely print errors to fd 1 because ...
  142. ^D
  143. %
  144. .EE
  145. .PP
  146. to add a note to the
  147. .B /n/sources/pwd-errors/notes
  148. file.
  149. .SH FILES
  150. .B /n/sources/patch
  151. .SH SOURCE
  152. .B /rc/bin/patch
  153. .SH SEE ALSO
  154. .IR diff (1)
  155. .br
  156. .B http://plan9.bell-labs.com/wiki/plan9/How_to_contribute