db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jean T. Anderson" <...@bristowhill.com>
Subject Re: Questions about committing doc patches
Date Mon, 04 Dec 2006 19:47:00 GMT
Laura Stewart 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  ?

If you open a file that was created on a different architecture, then
line endings will be different, and subversion will prevent you from
committing the changes to that file.

On Linux when I edit a file that was created on Windows, a "dos" flag
alerts me to that.

I'm not quite sure what you might see on a Windows machine if you open a
UNIX file in the editor. Anybody have any suggestions on how to tell?

The unix2dos and dos2unix command work "in place", so the syntax would be:

    unix2dos filename

You're on a Windows machine, right?  I think you can, to be on the safe
side, simply run that unix2dos command. If something needs to be
changed, it will be.

> 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.

Up in the "How to create a patch" section, it tells contributers to
create the patch from the trunk relative to the current working
directory, like this:

   svn diff > xyz.diff
   svn diff src/tuning > xyz.diff

Since we tell contributors to create the patch in the trunk directory,
you should apply the patch also in the trunk directory.  And since we
provide a suggestion relative to the current directory, the "-p0"
indicates that no leading characters need to be stripped in the path
locations in the file. --I'm not sure this is strictly necessary.
Comments, anyone?

useful references include:

> 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?

yes, that's correct.

If the contributor did not 'svn add' the file to the local working
directory, then the 'svn diff' command would not include that change.

> 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.

good point -- this section could use some specific examples and a
reference to the documentation at:


I typically commit like this for changes to the reference guide:

   svn commit src/ref

That pulls up an edit window into which I type something like:

   DERBY-XYZ Modified foo in bar.
   Patch contributed by Contributor <contributor email>

you can also do ....

   svn commit --message "DERBY-XYZ Modified foo in bar. Patch
contributed by Contributor <contributor email>" src/ref

or you can stuff that message in a file and do ....

   svn commit --file /full/path/to/file src/ref

To catch changes across multiple books I do:

   svn commit src

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

I make sure that the doc build succeeds for html, html book, and pdf.

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

yes, you'll see some sort of error, which you can post to derby-dev for
help resolving.

> What if a patch has to be backed out?

A wiki page tells you how to back out a change, but also feel free to
post for help:


The first commit is always the most intimidating.



View raw message