tutorial for patch

Reference: /n/patches.lsub.org/patch/hgcure
Date: Thu Apr 19 18:42:30 CES 2012
Signed-off-by: nemo@lsub.org

--- /sys/doc/patch.ms	Thu Jan  1 00:00:00 1970
+++ /sys/doc/patch.ms	Thu Apr 19 18:22:58 2012
@@ -0,0 +1,359 @@
+.FP lucidasans
+.HTML "Cares for Mercury Poisoning
+.TL
+Cares for Mercury Poisoning
+.br
+A tutorial for NIX's patch(1)
+.AU
+Francisco J. Ballesteros
+nemo@lsub.org
+.AB
+Mercury poisoning (also known as hydrargyria or mercurialism) is a
+disease caused by exposure to mercury or its compounds.
+This document describes how to use NIX's patch(1) to avoid
+exposure to dangerous metal compounds.
+.AE
+.SH
+Motivation
+.PP
+Plan 9 uses patches for sending contributions and a file replica tool to update
+installations. For some time, NIX used mercurial to propagate updates and contributions.
+But this had a number of problems.
+.IP 1
+The tool is not well suited to distribute binaries and does not preserve permissions.
+.IP 2
+The Plan 9 support for the tool is buggy, to say the least.
+.IP 3
+The tool is a departure from UNIX development in that you lose control over your
+files, and it's not easy to edit updates and/or fix problems when they happen.
+.IP 4
+Last but not least, it's not fun.
+.LP
+As an effort to make it easier and more amenable to contribute to NIX and to
+update NIX installations,
+.I patch (1)
+was written.
+.PP
+.I Patch
+is a set of simple scripts that try to preserve the following properties:
+.IP 1
+Patches should have an easy to understand structure. If there are problems, users
+should be able to edit them and/or fix them.
+.IP 2
+Patches should not depend on time-stamps, or other coherency enforcing
+mechanisms that force users to remove everything, and reinstall everything to
+get back into a coherent state. This happen to some replica users.
+.IP 3
+Patches should respect changes made to a local installation, and respect the
+user's freedom to customize the local system.
+.SH
+User interface
+.LP
+There are a few scripts available:
+.IP \(bu
+.I Patch/create
+can be used to create a patch.
+.IP \(bu
+.I Patch/pull
+can be used to update a local installation.
+.LP
+Other tools are aimed at people maintaining the distribution, and will be
+described later.
+.SH
+Patch creation
+.LP
+To create a patch, you can supply a list of files (and/or directories!) that
+change. Perhaps some of them have been removed, in which case the patch
+will try to remove them when applied. For example:
+.P1
+; rm -rf /386/bin/hg /sys/src/cmd/hg
+; patch/create noexposure nemo@lsub.org /386/bin/hg /sys/src/cmd/hg <<EOF
+Remove things dangerous for health.
+EOF
+;
+.P2
+.LP
+would create a patch called
+.I noexposure
+that would remove the named files when applied. Well, actually, it would not remove
+anything, but print commands you can run to remove them.
+.PP
+A more usual example is creating a patch that adds or edits some files:
+.P1
+; patch/create pwd-errors user@host.dom /sys/src/cmd/pwd.c /386/bin/pwd
+Fix pwd to print errors to fd 2 rather than 1.
+^D
+.P2
+.LP
+This creates a patch would change
+.I pwd
+when applied, and include a new binary for the command.
+.PP
+The created patch is kept at
+.I patches.lsub.org
+for others to look, until it's applied or forgotten.
+.SH
+Listing patches
+.LP
+At any time, you can run
+.I patch/list
+to see which patches are still out for discussion, but are not yet applied to the
+distribution:
+.P1
+; patch/list
+Apr 18 11:55 morepmc: Changes in the pmc that somehow got lost.
+Apr 19 05:55 cppnsec: The change in nsec() not to cache fds broke cpp.
+Apr 19 07:00 liberror: rename nerrors to errstacksize in liberror
+Apr 19 10:10 plan9-20120419: Sync with plan 9 as of today.
+Apr 19 10:20 realloc: Ptal, I followed what lucio/forsyth suggested and added a delta variable.
+.P2
+.LP
+You could also list all the patches, including those already applied:
+.P1
+; patch/list -a
+Apr 13 10:49 applied newprocess: Describe the new contribution process using patch(1).
+Apr 13 10:52 applied patchman: man updated for nix patch(1).
+.B ...
+.P2
+.LP
+Or ask for more information about one patch (or all patches):
+.P1
+; patch/list -v newup
+applied: newup
+date: Apr 18 09:55
+	New version of up to use in the upcomming patch/pullbin.
+from: nemo@lsub.org
+files:
+	/386/bin/up up
+	/sys/src/cmd/up.c up.c
+	/sys/man/1/up up.1
+removed:
+.P2
+.LP
+Under
+.I files
+you get a list of files that are new or changed (they are listed in a file named
+.I files
+within the patch directory).
+Under
+.I removed
+you get a list of files that are going to be removed (listed in a file named
+.I removed
+within the patch directory).
+.SH
+Pulling patches
+.LP
+To get your NIX installation up to date with respect to the distribution, you can run
+.I patch/pull
+as shown:
+.P1
+; patch/pull
+patch/apply creepyhalt
+/dist/patch/creepyhalt
+merge...conflicts merging /sys/src/cmd/creepy/9p.c; 
+	see /n/dist/dist/patch/creepyhalt/9p.c.new
+conflicts merging /sys/src/cmd/creepy/cfg.c;
+	see /n/dist/dist/patch/creepyhalt/cfg.c.new
+conflicts merging /sys/src/cmd/creepy/fsys.c;
+	see /n/dist/dist/patch/creepyhalt/fsys.c.new
+conflicts merging /sys/src/cmd/creepy/ix.c;
+	see /n/dist/dist/patch/creepyhalt/ix.c.new
+exiting without changes
+apply failed
+.P2
+.LP
+In this example, we have shown that
+.I apply
+detected some local changes and declared a conflict between the patch and your
+local editions.
+.PP
+.I Patch/pull
+takes all the patches applied to the main distribution an applies one by one to your tree
+until one fails or all have been applied.
+.PP
+If we have our
+.I / '' ``
+mounted read-only, or want to pull to a different tree, we can bind at
+.I /n/dist
+the tree to be patched. If there is no tree bound there,
+.I pull
+(or actually,
+.I apply )
+binds your
+.I / '' ``
+directory there.
+For example, under 9vx we could:
+.P1
+; bind -c '#Z/usr/nemo/nix-os' /n/dist 
+; patch/pull
+.B ...
+.P2
+.SH
+Conflicts
+.LP
+What do we do upon conflicts? Here is where the simple structure of a patch helps.
+In the example of the last section, we had conflicts for files:
+.I 9p.c ,
+.I cfg.c ,
+and
+.I ix.c .
+.PP
+First, we have to see what to do. As you may note from the output shown in the
+example of the previous section, you were asked to see files like
+.I /n/dist/dist/patch/creepyhalt/9p.c.new .
+.PP
+In your local tree, that file is actually at
+.I /dist/patch/creepyhalt/9p.c.new .
+Patches that are being applied are copied to
+.I /dist/patch
+where it's more convenient for you to edit and/or adjust them at will before
+retrying to apply them.
+.PP
+The original file by the time of the patch creation for
+.I 9p.c
+can be found in
+.I 9p.c.orig ,
+at the patch directory. So, this reports the diferences between what you
+were expected to have, and your local version for the file:
+.P1
+; diff /dist/patch/creepyhalt/9p.c.orig /sys/src/cmd/creepy/9p.c
+31c31
+< ninestats(char *s, char *e, int clr, int verb)
+---
+> ninestats(char *s, char *e, int clr)
+.B ...
+.P2
+.LP
+You may take several courses of action:
+.IP \(bu
+Drop your changes. This can be done by simply copying the original file
+as it was expected to be to your file:
+.P1
+; cp -x /dist/patch/creepyhalt/9p.c.orig /sys/src/cmd/creepy/9p.c
+.P2
+.LP
+.IP \(bu
+Drop the changes in the distribution. Easy!, just remove the file from the
+list of files to be patched:
+.P1
+; B /dist/patch/creepyhalt/files
+.I "... edit the file to remove the line for 9p.c ...
+.P2
+.LP
+.IP \(bu
+Hand-edit the merge that failed.
+.P1
+; cp -x /dist/patch/creepyhalt/9p.c.new /sys/src/cmd/creepy/9p.c
+; B /sys/src/cmd/creepy/9p.c
+.I "... locate the <<<<< and >>>> lines and edit at will ...
+; B /dist/patch/creepyhalt/files
+.I "... edit the file to remove the line for 9p.c ...
+.P2
+.IP
+An alternative could be to to copy the
+.I 9p.c.new
+to
+.I 9p.c
+in the patch directory, and then  copy
+.I 9p.c.orig
+from the patch directory to your local version, after editing
+.I 9p.c.new .
+.LP
+In general, you are welcome to edit the
+.I /dist/patch/*/files
+and
+.I /dist/patch/*/removed
+files that list new or changed files and removed files.
+.PP
+After resolving the conflicts, you can run
+.I patch/pull
+again. It will use your local version for the patch as kept in
+.I /dist/patch .
+.PP
+Another trick is to adjust the contents of
+.I /dist/patch/applied .
+That file contains the names of patches that have been applied.
+Thus, you can add a name there to skip or ignore that patch.
+.I Pull
+takes the list of applied patches from the main distribution, your one,
+and then goes one by one trying to apply patches that you have not yet applied.
+This command does also the trick:
+.P1
+; patch/applied creepyhalt
+.P2
+.LP
+In this section we could see conflicts for files that exist. However, the conflict
+may happen because the file was removed, or because it was not removed.
+The process in this case is exactly the same. When the
+.I .orig
+file does not exist in the patch directory, that means that the file was not
+expected to exist in your tree.
+.PP
+Also, files to be removed when applying the patch are simply listed at
+.I /dist/patch/*/removed ,
+and you are of course welcome to edit that file.
+.PP
+The apply process will usually not remove any of your files, but print
+commands that you could run to remove them if you want.
+.SH
+Reviewing code
+.LP
+You might want to try a patch to drop some comments on it for reviewing.
+This can be done as follows:
+.P1
+; patch/apply newup
+/dist/patch/newup
+merge...backup...copy...
+cpfile up /n/dist/386/bin/up
+cpfile up.c /n/dist/sys/src/cmd/up.c
+cpfile up.1 /n/dist/sys/man/1/up
+done
+.P2
+.LP
+Now you can play with the new
+.I up
+from the patch. Once you are done, you can get back to where you were
+before applying this patch by running:
+.P1
+; patch/undo newup
+.B ...
+.P2
+.LP
+This relies on the
+.I .backup
+files copied to the patch directory to restore your previous state.
+.PP
+.SH
+Updating a patch
+.LP
+So, what do we do if due to a review or to a change of mind we
+want to update a patch? Easy. We just create it again with the new
+set of files relevant for the patch (added, changed, or removed files).
+A new mail will be sent notifying the patch creation, and that must
+be understood as an update for the patch.
+The old versions for the patch are kept in sibling (renamed) directories,
+until the patch is applied to the main distribution.
+.SH
+When everything fails...
+.LP
+Remember that patches can be edited.
+First, you should probably make sure that your set of
+.I patch
+scripts is up to date. Newer versions of
+.I patch
+take care of that by showing you which commands you have to run
+to update it when needed. But, in any case, we can always:
+.P1
+; 9fs sources.lsub.org
+post...
+; fcp -x /n/sources.lsub.org/nix/rc/bin/patch/* /rc/bin/patch
+.P2
+.LP
+Or using
+.I up (1)
+perhaps...
+.P1
+; 9fs sources.lsub.org
+; up /n/sources.lsub.org/nix/rc/bin/patch /rc/bin/patch |rc
+.P2
+.LP