db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew McIntyre" <mcintyr...@gmail.com>
Subject Re: Questions about committing doc patches
Date Mon, 04 Dec 2006 19:45:04 GMT
On 12/4/06, Laura Stewart <scotsmatrix@gmail.com> wrote:
> As a new committer, I will be looking at doc patches to commit.
>
> I have looked over the instructions at:
> http://db.apache.org/derby/manuals/dita.html#Committing+documentation+patches
> and have a few questions.  After I understand these steps, we might
> want to update the steps with a little more explanation :-)
>
> Step 3
> If your machine is a different architecture from the machine on which
> the patch was created, convert the file.
>
> Question - Aren't all patch files diff files? How will I know that the
> patch was created on a different machine?  I use Windows, what should
> I look for to know that the patch was created in UNIX?  Is the syntax:
> unix2dos patch.diff      or       unix2dos > patch.diff  ?

I think step 3 should be removed. All patch files will be unified
format diff files, as output by svn diff. Any patch program should be
able to compensate for line-ending differences, since presumably on
Windows you'll be using Cygwin's patch program. So, there should never
be a need to convert the line-endings in the file.

> Step 4
> Apply the patch:
> patch -p0 < patch.diff
>
> Question - I am not sure what this syntax means.  The name of the
> patch appears to be patch.diff.  What then is -p0?  The directional
> arrow indicates that the patch.diff should be going to (or redirected
> to) -p0.  Please explain the syntax to me.

-p0 is an optional parameter to the patch program, which directs the
patch program to strip that number of leading slashes and path parts
from the filenames in the patch before attempting to apply the patch
to local files. See the man page for the patch command for more
information. Command line syntax dictates that redirection applies to
the command in question, not any of its arguments or options, <
patch.diff indicates redirecting stdin for the patch command to the
file patch.diff

> Step 5
> Check modifications with 'svn status' and add any files that need it:
>
> Question - So I run "svn status".  Even though the person who
> submitted the patch has already added new files using "svn add", I
> will need to do it again for the new files?  Is that because the svn
> add is only applied to the local copy of the source files?

Correct. The patch command won't apply svn-specific output in the
patch file like add or property changes to your local changes. If the
patch file contains new files or property changes, you'll need to svn
add them to your local checkout before committing the patch. Running
svn stat in your local checkout will show the new files with a '?' for
the status marker on the left side of the output, since your local svn
checkout doesn't know about the files.

Be sure that you set up your subversion .config file as indicated here:

http://www.apache.org/dev/version-control.html#https-svn

Also, you'll need to add a couple of lines to your subversion .config
that are Derby-specific, particularly .dita and .out should be in
there:

*.dita = svn:eol-style=native
*.out = svn:eol-style=native

> Step 7
> Commit the changes.
>
> Question - There are no instructions here... is this simply done by
> running an svn commit command? Is there anything else that needs to be
> specified? What if the patch was not created at the trunk level?  We
> should document (somewhere) what to do in that case.

Well, I guess there are other steps after running 'svn commit' - enter
a change description, save and quit editor, wait and confirm that the
change was successfully committed to the repository by noting the
change number.

If a patch was not created at the trunk level, the committer must
change directory into the same level at which the patch was created in
order to apply the patch. e.g. if the patch was created in the src
directory of the doc tree, then another person applying the patch to
their checkout will need to be in their src directory when running the
patch command.

> Other questions -
>
> Are there any specific checks that committers perform when committing
> documentation (vs code) patches?

As with the code tree, it's always wise to make sure that everything
builds properly after applying the patch.

> What if there is a problem with the commit?  Will I see something immediately?

Yes, svn will issue an error message after 'Transmitting files...' and
you will not receive a change number for your commit.

> What if a patch has to be backed out?

svn merge -r {rev}:{rev-1} https://svn.apache.org/repos/asf/db/derby/docs/trunk/

svn will reverse the application of the change in the repository, if
you specify a revision range that goes from a higher revision to a
lower one.

svn merge -r 408659:408658 https://svn.apache.org/repos/asf/db/derby/docs/trunk/

andrew

Mime
View raw message