You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by Laura Stewart <sc...@gmail.com> on 2006/12/04 20:23:19 UTC
Questions about committing doc patches
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 ?
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.
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?
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.
Other questions -
Are there any specific checks that committers perform when committing
documentation (vs code) patches?
What if there is a problem with the commit? Will I see something immediately?
What if a patch has to be backed out?
Thanks!
--
Laura Stewart
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Yip Ng wrote:
> On 12/4/06, Andrew McIntyre <mc...@gmail.com> wrote:
>
>>
>> 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
>
>
>
> Just a side note, I see that in Step 1 of the "Committing
> documentation patches" section
> (and various other places), it directs the user to
> ~/.subversion/config, wouldn't it be better to just say "subversion
> config file" instead? On Windows platform, this config file is stored
> in different location in the system.
>
> http://svnbook.red-bean.com/en/1.1/ch07.html
good idea, Yip, thanks -- and thanks for the doc pointer.
-jean
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Myrna van Lunteren wrote:
> On 12/4/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
>
>> Myrna van Lunteren wrote:
>> ...
>> > One more comment - if it's been covered already or too obvious, sorry
>> > - but if you're ready to do svn commit, ensure that when you do svn
>> > info, you see you have checked out https://.... (and not http://...)
>>
>> the example shows https, but doesn't explain it is required for
>> committing changes. I'll add a note.
>>
>> > and that you've got an environment variable $SVN_EDITOR set to some
>> > editor accessible on your PATH. (to vi, for example).
>>
>> good point. On a Windows machine what would you typically set
>> SVN_EDITOR to?
>>
>> -jean
>>
>>
> I have a shell environment on Windows, so I use vi...But I just
> experimented and notepad works as well.
And I noticed the instructions at
http://svnbook.red-bean.com/en/1.1/ch07.html also show how to set
notepad using the subversion editor-cmd property (if not set, then it'll
look for SVN_EDITOR). So I just committed a change that references that
web site page.
Thanks for all the feedback, Myrna, Laura, Andrew, and Yip. I committed
a change to the web site that doesn't get quite as verbose as these nice
emails, but does include lots of doc pointers. That change should be
visible within an hour or so.
-jean
Re: Questions about committing doc patches
Posted by Myrna van Lunteren <m....@gmail.com>.
On 12/4/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
> Myrna van Lunteren wrote:
> ...
> > One more comment - if it's been covered already or too obvious, sorry
> > - but if you're ready to do svn commit, ensure that when you do svn
> > info, you see you have checked out https://.... (and not http://...)
>
> the example shows https, but doesn't explain it is required for
> committing changes. I'll add a note.
>
> > and that you've got an environment variable $SVN_EDITOR set to some
> > editor accessible on your PATH. (to vi, for example).
>
> good point. On a Windows machine what would you typically set SVN_EDITOR to?
>
> -jean
>
>
I have a shell environment on Windows, so I use vi...But I just
experimented and notepad works as well.
Myrna
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Myrna van Lunteren wrote:
...
> One more comment - if it's been covered already or too obvious, sorry
> - but if you're ready to do svn commit, ensure that when you do svn
> info, you see you have checked out https://.... (and not http://...)
the example shows https, but doesn't explain it is required for
committing changes. I'll add a note.
> and that you've got an environment variable $SVN_EDITOR set to some
> editor accessible on your PATH. (to vi, for example).
good point. On a Windows machine what would you typically set SVN_EDITOR to?
-jean
Re: Questions about committing doc patches
Posted by Myrna van Lunteren <m....@gmail.com>.
On 12/4/06, Yip Ng <yi...@gmail.com> wrote:
> On 12/4/06, Andrew McIntyre <mc...@gmail.com> wrote:
> >
> > 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
>
>
> Just a side note, I see that in Step 1 of the "Committing
> documentation patches" section
> (and various other places), it directs the user to
> ~/.subversion/config, wouldn't it be better to just say "subversion
> config file" instead? On Windows platform, this config file is stored
> in different location in the system.
>
> http://svnbook.red-bean.com/en/1.1/ch07.html
>
> Regards,
> Yip Ng
>
One more comment - if it's been covered already or too obvious, sorry
- but if you're ready to do svn commit, ensure that when you do svn
info, you see you have checked out https://.... (and not http://...)
and that you've got an environment variable $SVN_EDITOR set to some
editor accessible on your PATH. (to vi, for example).
Myrna
Re: Questions about committing doc patches
Posted by Yip Ng <yi...@gmail.com>.
On 12/4/06, Andrew McIntyre <mc...@gmail.com> wrote:
>
> 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
Just a side note, I see that in Step 1 of the "Committing
documentation patches" section
(and various other places), it directs the user to
~/.subversion/config, wouldn't it be better to just say "subversion
config file" instead? On Windows platform, this config file is stored
in different location in the system.
http://svnbook.red-bean.com/en/1.1/ch07.html
Regards,
Yip Ng
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Andrew McIntyre wrote:
> On 12/4/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
>
>> Andrew McIntyre wrote:
>> > On 12/4/06, Laura Stewart <sc...@gmail.com> wrote:
>> ...
>> >> 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.
>> >
>>
>> I get errors on Linux if I don't convert the file. You don't have this
>> problem?
>
> Nope, I get:
>
> patching file path/to/file
> (Stripping trailing CRs from patch.)
>
> with GNU patch v2.5.8.
ok, let's remove that step 3 then. (I'm on an older version of patch,
will update).
-jean
Re: Re: Questions about committing doc patches
Posted by Andrew McIntyre <mc...@gmail.com>.
On 12/4/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
> Andrew McIntyre wrote:
> > On 12/4/06, Laura Stewart <sc...@gmail.com> wrote:
> ...
> >> 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.
> >
>
> I get errors on Linux if I don't convert the file. You don't have this
> problem?
Nope, I get:
patching file path/to/file
(Stripping trailing CRs from patch.)
with GNU patch v2.5.8.
andrew
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Andrew McIntyre wrote:
> On 12/4/06, Laura Stewart <sc...@gmail.com> wrote:
...
>> 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.
>
I get errors on Linux if I don't convert the file. You don't have this
problem?
-jean
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
On 12/15/06, Bryan Pendleton <bp...@amberpoint.com> wrote:
> > I am writing up a set of steps for myself now so that I don't forget
> > what to do (since some steps only need to be done once). Earlier in
> > this tread we addressed what needs to be done if a new file is add
> > (svn add). What if a new file is deleted?
>
> You might want to edit/enhance these wiki pages:
>
> http://wiki.apache.org/db-derby/DerbyCommitHowTo
> http://wiki.apache.org/db-derby/AddedOrDeletedFilesInDiff
>
> thanks,
>
> bryan
>
>
>
Thanks Bryan. I didn't know about these pages.
I was following the instructions on:
http://db.apache.org/derby/manuals/dita.html#Committing+documentation+patches
since my primary focus will be doc patches.
--
Laura Stewart
Re: Questions about committing doc patches
Posted by Bryan Pendleton <bp...@amberpoint.com>.
> I am writing up a set of steps for myself now so that I don't forget
> what to do (since some steps only need to be done once). Earlier in
> this tread we addressed what needs to be done if a new file is add
> (svn add). What if a new file is deleted?
You might want to edit/enhance these wiki pages:
http://wiki.apache.org/db-derby/DerbyCommitHowTo
http://wiki.apache.org/db-derby/AddedOrDeletedFilesInDiff
thanks,
bryan
Re: Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
On 12/15/06, Andrew McIntyre <mc...@gmail.com> wrote:
> While it's a little odd that it asked for your password after printing
> the first Sending message, the files are actually transmitted after it
> prints the 'transmitting file data' message. It will then print one
> period per file transmitted.
>
> I've received the mail for your commit, and it should appear in the
> derby-commits archive shortly.
>
> andrew
>
Whew! I guess that means that I did it !!!
I am writing up a set of steps for myself now so that I don't forget
what to do (since some steps only need to be done once). Earlier in
this tread we addressed what needs to be done if a new file is add
(svn add). What if a new file is deleted?
--
Laura Stewart
Re: Re: Questions about committing doc patches
Posted by Andrew McIntyre <mc...@gmail.com>.
On 12/15/06, Laura Stewart <sc...@gmail.com> wrote:
> Well, it seems that though I did the commit correctly... Here is what
> cygwin gave me:
>
> $ svn commit --message "DERBY-2125 Modified two files about installing Derby. P
> atch derby2125.diff contributed by Kim Haase." src/getstart
>
> Sending src\getstart\cgsinstallingderby.dita
> Authentication realm: <https://svn.apache.org:443> ASF Committers
> Password for 'stewartl': ********
> Authentication realm: <https://svn.apache.org:443> ASF Committers
> Username: scotsmatrix
> Password for 'scotsmatrix': ********
> Sending src\getstart\gsconrefs.dita
> Transmitting file data ..
> Committed revision 487665.
>
> I am not sure that I understand why one file was sent first and then
> the other file sent...
While it's a little odd that it asked for your password after printing
the first Sending message, the files are actually transmitted after it
prints the 'transmitting file data' message. It will then print one
period per file transmitted.
I've received the mail for your commit, and it should appear in the
derby-commits archive shortly.
andrew
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
Well, it seems that though I did the commit correctly... Here is what
cygwin gave me:
$ svn commit --message "DERBY-2125 Modified two files about installing Derby. P
atch derby2125.diff contributed by Kim Haase." src/getstart
Sending src\getstart\cgsinstallingderby.dita
Authentication realm: <https://svn.apache.org:443> ASF Committers
Password for 'stewartl': ********
Authentication realm: <https://svn.apache.org:443> ASF Committers
Username: scotsmatrix
Password for 'scotsmatrix': ********
Sending src\getstart\gsconrefs.dita
Transmitting file data ..
Committed revision 487665.
I am not sure that I understand why one file was sent first and then
the other file sent...
--
Laura Stewart
Re: Questions about committing doc patches
Posted by Bryan Pendleton <bp...@amberpoint.com>.
>> $ svn commit --message "DERBY-2125 Modified two files about installing
>> Derby. Patch derby2125.diff contributed by Kim Haase" src/getstart
>
> And now I can't get back to the $ prompt...
Probably the shell has become confused about your quotation marks and it
thinks it's still inside a string, looking for the close quote.
You could terminate the close quote, or you could try to interrupt the
in-flight svn command with control-c.
thanks,
bryan
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
On 12/15/06, Laura Stewart <sc...@gmail.com> wrote:
> Another question... when I try to commit the patch, I use the
> following but all I get from cygwin is a > prompt. What am I doing
> wrong?
>
> $ svn commit --message "DERBY-2125 Modified two files about installing
> Derby. Patch derby2125.diff contributed by Kim Haase" src/getstart
>
> Laura Stewart
>
And now I can't get back to the $ prompt...
--
Laura Stewart
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
Another question... when I try to commit the patch, I use the
following but all I get from cygwin is a > prompt. What am I doing
wrong?
$ svn commit --message "DERBY-2125 Modified two files about installing
Derby. Patch derby2125.diff contributed by Kim Haase" src/getstart
Laura Stewart
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> When you typically build the output to check for errors, do you run
> each one separately or do you run them all together with ant
> (bookname) ?
I usually do 'ant (bookname)' because that will easily test the html,
html book, and pdf generation.
Every now and then I do an 'ant all', but I don't do that for each patch
I test.
-jean
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
When you typically build the output to check for errors, do you run
each one separately or do you run them all together with ant
(bookname) ?
--
Laura Stewart
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
On 12/15/06, Daniel John Debrunner <dj...@apache.org> wrote:
> Laura Stewart wrote:
> > When I open a cygwin window, it takes me to this path
> > C:\Documents and Settings\stewartl
> > and won't let me change to another directory.
> > All of my Derby stuff is in
> > C:\Authoring\Derby
> >
> > Any ideas on how I can either change the default path for cygwin or
> > force it to let me change directories?
>
> What error do you get? I would expect this to work
>
> cd c:/Authoring/derby
>
> That's what I do in my environment.
>
> cygwin does maintain a unix like concept of the file system, but also
> accepts windows paths with a forward slash.
>
> Dan.
>
>
>
The slash, that was the problem. I was using backslash instead of
forward slash. Thanks!
--
Laura Stewart
Re: Questions about committing doc patches
Posted by Daniel John Debrunner <dj...@apache.org>.
Laura Stewart wrote:
> When I open a cygwin window, it takes me to this path
> C:\Documents and Settings\stewartl
> and won't let me change to another directory.
> All of my Derby stuff is in
> C:\Authoring\Derby
>
> Any ideas on how I can either change the default path for cygwin or
> force it to let me change directories?
What error do you get? I would expect this to work
cd c:/Authoring/derby
That's what I do in my environment.
cygwin does maintain a unix like concept of the file system, but also
accepts windows paths with a forward slash.
Dan.
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
When I open a cygwin window, it takes me to this path
C:\Documents and Settings\stewartl
and won't let me change to another directory.
All of my Derby stuff is in
C:\Authoring\Derby
Any ideas on how I can either change the default path for cygwin or
force it to let me change directories?
--
Laura Stewart
Re: Questions about committing doc patches
Posted by Daniel John Debrunner <dj...@apache.org>.
Laura Stewart wrote:
> I am having trouble getting everything set up to commit patches.
>
> I feel like a dolt.
>
> #1 - I finally found the config file under the following path.
>
> C:\Documents and Settings\stewartl\Application Data\Subversion
>
> But this can't be the correct file. Almost all of the rows are
> commented out... which doesn't sound correct. So I thought that there
> must be another config file on my machine that was created when I
> first started the Derby project. Especially since the instructions
> here:
>
> http://db.apache.org/derby/manuals/dita.html#Setting+up+your+environment
>
> Have users add these 3 lines at the bottom
>
> *.dita = svn:eol-style=native
> *.ditamap = svn:eol-style=native
> *.out = svn:eol-style=native
>
> But those lines are missing from the config file that I located here
>
> C:\Documents and Settings\stewartl\Application Data\Subversion
I think that's the correct file. The version installed by subversion by
default has all (most?) of the configurations options there as examples
but commented out so you get a standard configuration.
You can add those lines into the config file in the correct section
[auto-props] and I think you need to uncomment out the header for that
section.
This is the tail end of my config file.
[auto-props]
# *.c = svn:eol-style=native
# *.cpp = svn:eol-style=native
# *.h = svn:eol-style=native
# *.dsp = svn:eol-style=CRLF
# *.dsw = svn:eol-style=CRLF
# *.sh = svn:eol-style=native;svn:executable
# *.txt = svn:eol-style=native
# *.png = svn:mime-type=image/png
# *.jpg = svn:mime-type=image/jpeg
# Makefile = svn:eol-style=native
*.txt = svn:eol-style=native
*.java = svn:eol-style=native
*.out = svn:eol-style=native
*.sql = svn:eol-style=native
*.xml = svn:eol-style=native
Dan.
Re: Questions about committing doc patches
Posted by Bryan Pendleton <bp...@amberpoint.com>.
> I feel like a dolt.
Please don't! This is a complicated process, and it takes everybody
a while to get their system set up successfully.
> #3 - Myrna commented "and that you've got an environment variable
> $SVN_EDITOR set to some editor accessible on your PATH. (to vi, for
> example)."
FWIW, I don't do this part. Instead, I *always* prepare commit messages
ahead of time in simple text files, and then when I commit I use the
"--file" argument to pass my file to subversion. This way you can use
whatever editor you want, without having to figure out how to integrate
it with subversion.
There are many roads to Rome, and I don't think you *have* to have
your environment be identical to somebody else's. The important part
is that you understand how your environment works, and you can do the
necessary tasks successfully.
thanks,
bryan
Re: Questions about committing doc patches
Posted by Laura Stewart <sc...@gmail.com>.
I am having trouble getting everything set up to commit patches.
I feel like a dolt.
#1 - I finally found the config file under the following path.
C:\Documents and Settings\stewartl\Application Data\Subversion
But this can't be the correct file. Almost all of the rows are
commented out... which doesn't sound correct. So I thought that there
must be another config file on my machine that was created when I
first started the Derby project. Especially since the instructions
here:
http://db.apache.org/derby/manuals/dita.html#Setting+up+your+environment
Have users add these 3 lines at the bottom
*.dita = svn:eol-style=native
*.ditamap = svn:eol-style=native
*.out = svn:eol-style=native
But those lines are missing from the config file that I located here
C:\Documents and Settings\stewartl\Application Data\Subversion
#2 - One of the comments above says:
"Be sure that you set up your subversion .config file as indicated here:
http://www.apache.org/dev/version-control.html#https-svn
But it is not clear to me what needs to be done from that page... is
it that I add the following to the config file?
svn propset svn:eol-style native
I am assuming that the "test.txt" is just an example... and doesn't
need to be added.
#3 - Myrna commented "and that you've got an environment variable
$SVN_EDITOR set to some editor accessible on your PATH. (to vi, for
example)."
So does this means that I need to do 2 things - set SVN_EDITOR=notepad
and ensure that the location of the notepad exe file is listed in the
PATH?
--
Laura Stewart
Re: Questions about committing doc patches
Posted by Andrew McIntyre <mc...@gmail.com>.
On 12/5/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
>
> Why the *.out files? I went ahead and added that to
> http://db.apache.org/derby/manuals/dita.html , but I just did a complete
> dita doc build and there weren't any .out files.
For test masters, which isn't doc-specific. I didn't realize the page
in question was actually specific to documentation commits.
andrew
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Andrew McIntyre wrote:
...
> 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
Why the *.out files? I went ahead and added that to
http://db.apache.org/derby/manuals/dita.html , but I just did a complete
dita doc build and there weren't any .out files.
just curious,
-jean
Re: Questions about committing doc patches
Posted by Andrew McIntyre <mc...@gmail.com>.
On 12/4/06, Laura Stewart <sc...@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
Re: Questions about committing doc patches
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
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:
http://linux.about.com/od/commands/l/blcmdl1_patch.htm
http://en.wikipedia.org/wiki/Patch_(Unix)
> 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:
http://svnbook.red-bean.com/en/1.1/re06.html
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:
http://wiki.apache.org/db-derby/HowToBackOutaChange
The first commit is always the most intimidating.
cheers,
-jean