You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by gm...@apache.org on 2006/08/26 11:44:53 UTC
svn commit: r437136 - /forrest/trunk/site-author/content/xdocs/howto-dev.xml
Author: gmcdonald
Date: Sat Aug 26 02:44:52 2006
New Revision: 437136
URL: http://svn.apache.org/viewvc?rev=437136&view=rev
Log:
Added in revert SVN changes section as per Jira Issue FOR-875
Modified:
forrest/trunk/site-author/content/xdocs/howto-dev.xml
Modified: forrest/trunk/site-author/content/xdocs/howto-dev.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/howto-dev.xml?rev=437136&r1=437135&r2=437136&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/howto-dev.xml (original)
+++ forrest/trunk/site-author/content/xdocs/howto-dev.xml Sat Aug 26 02:44:52 2006
@@ -224,6 +224,63 @@
svn update -r HEAD.
</source>
</section>
+ <section id="svn-merge">
+ <title>Reverting Changes using SVN Merge</title>
+ <p>You may want to revert some changes made to HEAD or may want to revert changes made
+ to an earlier revision that still exists in HEAD today.</p>
+ <p>This is where SVN Merge comes in handy. Taking the first scenario, here is an
+ example of reverting a change from HEAD to an earlier revision 300.</p>
+ <source>
+# reverting unneccesary changes to %FORREST_HOME%/site-author/content/xdocs/index.xml
+
+$ svn merge -r HEAD:300 /site-author/content/xdocs/index.xml /site-author/content/xdocs/index.xml
+
+# you should then get confirmation of this as :
+U /site-author/content/xdocs/index.xml
+
+# Then do an svn diff to verify the change is removed.
+$ svn diff
+...
+
+# Then commit the reverted changed file(s)
+
+$ svn commit -m "Undoing changes commited to index.xml in r300."
+Sending /site-author/content/xdocs/index.xml
+Transmitting file data .
+Committed revision 350.
+ </source>
+ <p>It should only be neccessary to specify a particular file to revert
+ with svn merge only if there are other changed files in that revision.</p>
+ <p> This second example assumes that way back in revision r303 only one change was
+ made to one file and that this is what we want to remove.</p>
+ <source>
+# reverting unneccessary change to /site-author/content/xdocs/index.xml
+# - this is the only changed file for this revision.
+
+svn merge -r 303:302
+
+# you should then get confirmation of this as "
+U index.xml
+
+# Then do an svn diff to verify the change is removed.
+$ svn diff
+...
+
+# Then commit the reverted changed file(s)
+
+$ svn commit -m "Undoing unwanted change to index.xml from r303."
+Sending index.xml
+Transmitting file data .
+Committed revision 351.
+ </source>
+ <p>The second example above will revert any changes made by revision 303
+ from revision 302 and then applies it to the current revision HEAD which in
+ this example has become r351. Also note that the changes have NOT been removed
+ from ANY revisions in between r303 and r350, so rolling back to any of these
+ revisions will add the un-needed change back in again.</p>
+ <p> More information can be found at <a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2">Common use-cases for
+ merging</a> section of the Red Bean SVN Book.</p>
+ </section>
<section id="svn-patch">
<title>Creating patches</title>
Re: level of detail for docs (Was: svn commit: r437136)
Posted by David Crossley <cr...@apache.org>.
Gav.... wrote:
>
> Exactly that, if there are those that wander across my minitutorials.com
> Site, expecially the Apache web server installation tutorials, you would
> Notice my style of writing on there at least is aimed at beginners and
> Very detailed and very pandering I suppose in my style. I've been doing
> It so long I must remember that we don't have that same audience here and
> To maybe stop being so detailed perhaps.
It will be very hard for the small Forrest project to
maintain verbose documentation.
This is getting closer to my main reason for raising these
concerns. We need to focus on Forrest documentation.
We also need to concentrate on our target audience. We decided
that Forrest is still in the stage of trying to attract
developers rather than beginner users (we should document
that so that newcomers like Gavin are on the same wavelength).
We said that we primarily need to get a strong developer base.
So our documentation should reflect that, and not get into
ponderous descriptions for beginners.
-David
Re: level of detail for docs (Was: svn commit: r437136)
Posted by Ross Gardler <rg...@apache.org>.
Gav.... wrote:
...
> Pointers are a great help, the balance between too much
>
>>detail and not enough is a hard one but I would err on the side of
>>caution,
>
>
> Meaning err on the side of not enough in case too much gets it wrong ?
Not so much "gets it wrong" as "fails to provide complete details". If
we make it look like we are trying to provide documentation then people
will ask us to clarify and expand that documentation. This is fine for
documents about our own code, but we don't want to waste effort
documenting someone elses projects here.
As David hinted, we would be better providing patches to the SVN
documentation effort than duplicating things here. It doesn't really
take that much more effort, do they have a FAQ, your entry here would be
ideal for such a document. All that needs to be done is to drop it into
their issue tracker and let them deal with it as they see fit.
Ross
RE: level of detail for docs (Was: svn commit: r437136)
Posted by "Gav...." <br...@brightontown.com.au>.
> -----Original Message-----
> From: Ross Gardler [mailto:rgardler@apache.org]
> Sent: Tuesday, 29 August 2006 4:34 PM
> To: dev@forrest.apache.org
> Subject: Re: level of detail for docs (Was: svn commit: r437136)
>
> David Crossley wrote:
> > Why do we need this level of detail? Surely the "SVN Book"
> > explains it better than we can.
> > http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2
>
> I would go for a half way between detail and easy lookup. What I mean
> is, it is useful to have a quick reminder on how to do something with a
> link to the full text in the SVN book. This way someone who doesn't know
> how to do it can look at the quick reference to find an easy link (which
> is easier than searching the SVN book). Those who can half remember how
> to do it but need a memory jogger with respect to syntax can just take a
> quick look on our page.
Ok, that's good, that is what I meant should I alter it to in my reply just
before I got to read This.
>
> It's all very well saying (to paraphrase) "Forrest devs should know how
> to do it", but we have to learn somewhere. When this came up the first
> time I asked on this list because I couldn't find it in the SVN Book.
> Nobody here knew how to do it. Eventually a solution was found (because
> it was asked shorlty afterwards on the Cocoon dev list too).
>
> I'm guessing Gav figured that, as a new developer who had to discover
> how to do this he would help tose coming later by documenting it in a
> simpler way.
Exactly that, if there are those that wander across my minitutorials.com
Site, expecially the Apache web server installation tutorials, you would
Notice my style of writing on there at least is aimed at beginners and
Very detailed and very pandering I suppose in my style. I've been doing
It so long I must remember that we don't have that same audience here and
To maybe stop being so detailed perhaps.
Pointers are a great help, the balance between too much
> detail and not enough is a hard one but I would err on the side of
> caution,
Meaning err on the side of not enough in case too much gets it wrong ?
just a syntax reference with a couple of basic examples and a
> link to the SVN book should do (i.e. lets not try and explain it, there
> are always exceptions).
Ok, the link is already there, I'll simplify and shorten the current
examples then, thanks for the comments.
Gav...
>
> Ross
>
>
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.405 / Virus Database: 268.11.6/429 - Release Date: 8/28/2006
Re: level of detail for docs (Was: svn commit: r437136)
Posted by Ross Gardler <rg...@apache.org>.
David Crossley wrote:
> Why do we need this level of detail? Surely the "SVN Book"
> explains it better than we can.
> http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2
I would go for a half way between detail and easy lookup. What I mean
is, it is useful to have a quick reminder on how to do something with a
link to the full text in the SVN book. This way someone who doesn't know
how to do it can look at the quick reference to find an easy link (which
is easier than searching the SVN book). Those who can half remember how
to do it but need a memory jogger with respect to syntax can just take a
quick look on our page.
It's all very well saying (to paraphrase) "Forrest devs should know how
to do it", but we have to learn somewhere. When this came up the first
time I asked on this list because I couldn't find it in the SVN Book.
Nobody here knew how to do it. Eventually a solution was found (because
it was asked shorlty afterwards on the Cocoon dev list too).
I'm guessing Gav figured that, as a new developer who had to discover
how to do this he would help tose coming later by documenting it in a
simpler way. Pointers are a great help, the balance between too much
detail and not enough is a hard one but I would err on the side of
caution, just a syntax reference with a couple of basic examples and a
link to the SVN book should do (i.e. lets not try and explain it, there
are always exceptions).
Ross
Re: level of detail for docs (Was: svn commit: r437136)
Posted by David Crossley <cr...@apache.org>.
Gav.... wrote:
>
> From: David Crossley
> >
> > Why do we need this level of detail?
>
> I was following the level of detail in other examples on the page and
> elsewhere on the site.
I meant that the SVN Book has all the information,
so why do we need to duplicate it.
> Surely the "SVN Book"
> > explains it better than we can.
> > http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2
>
> Yes that link was referred to in the emails linked to from the Forrest
> Issue. In the same email thread Ross mentioned he asked how it should
> Be done and apparently no one knew.
> It also states that Antonio stated that the svnbook docs were unclear
> In this regard. (Hence my attempt to forrest-ify it and make it clearer
> To forrest devs)
>
> > If not, then wouldn't it be better to submit a patch to that project.
>
> I have the time to dedicate to Forrest but none for redbean I'm afraid.
>
> > Sorry if i appear to be jumping on your changes. I am trying
> > to use your early contributions to provide guidance.
>
> No problem, thanks, hope my comments here don't make for excuses,
> Just trying to justify my commit :) (And partly why I'm picking
> Easy ones first as Im sure you noticed)
>
> > My concerns are that the Forrest Project should not need
> > to maintain such documentation and rather concentrate on
> > Forrest topics. Our time gets wasted.
>
> I agree, but the Issue asked for it.
>
> For example, i detect
> > some obscurities in what you wrote.
>
> Well, I tried to Forrest-ify it to be relevant, what is unclear ?
That misses my point. I would prefer not to spend time
attending to it. A simple link to SVN Book avoids that.
> > Also the "tips for developers" document is becoming bloated.
>
> Ok, the Issue mentioned this as a (perhaps) place to add it to.
>
> > Also ASF Committers should know how to do this stuff
> > or at least know to refer to the SVN Book.
>
> They should, I am confused now though, why was the Issue to add
> This stuff created in the first place?
As a reminder to refer people to SVN Book for
the background and the many uses of 'svn merge'.
> So now whats the plan, do you want me to truncate the info somewhat to
> Maybe one short example?
If it was me doing it, then i would put a simple
dot-point about making sure that the dev knows what
they are doing and link direct to the SVN Book section
which has full background info. They need to understand
any associated issues.
If svnbook section is unclear (note that i don't know
what Antonio is referring to) then add a simple entry
to the svnbook issue tracker, and link to that issue from
our docs.
-David
RE: level of detail for docs (Was: svn commit: r437136)
Posted by "Gav...." <br...@brightontown.com.au>.
> -----Original Message-----
> From: David Crossley [mailto:crossley@apache.org]
> Sent: Tuesday, 29 August 2006 9:09 AM
> To: Forrest Developers List
> Subject: level of detail for docs (Was: svn commit: r437136)
>
> Why do we need this level of detail?
I was following the level of detail in other examples on the page and
elsewhere on the site.
Surely the "SVN Book"
> explains it better than we can.
> http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2
Yes that link was referred to in the emails linked to from the Forrest
Issue. In the same email thread Ross mentioned he asked how it should
Be done and apparently no one knew.
It also states that Antonio stated that the svnbook docs were unclear
In this regard. (Hence my attempt to forrest-ify it and make it clearer
To forrest devs)
>
> If not, then wouldn't it be better to submit a patch to that project.
I have the time to dedicate to Forrest but none for redbean I'm afraid.
>
> Sorry if i appear to be jumping on your changes. I am trying
> to use your early contributions to provide guidance.
No problem, thanks, hope my comments here don't make for excuses,
Just trying to justify my commit :) (And partly why I'm picking
Easy ones first as Im sure you noticed)
>
> My concerns are that the Forrest Project should not need
> to maintain such documentation and rather concentrate on
> Forrest topics. Our time gets wasted.
I agree, but the Issue asked for it.
For example, i detect
> some obscurities in what you wrote.
Well, I tried to Forrest-ify it to be relevant, what is unclear ?
>
> Also the "tips for developers" document is becoming bloated.
Ok, the Issue mentioned this as a (perhaps) place to add it to.
>
> Also ASF Committers should know how to do this stuff
> or at least know to refer to the SVN Book.
They should, I am confused now though, why was the Issue to add
This stuff created in the first place?
>
> -David
So now whats the plan, do you want me to truncate the info somewhat to
Maybe one short example?
Thanks
Gav...
>
> > Author: gmcdonald
> > Date: Sat Aug 26 02:44:52 2006
> > New Revision: 437136
> >
> > URL: http://svn.apache.org/viewvc?rev=437136&view=rev
> > Log:
> > Added in revert SVN changes section as per Jira Issue FOR-875
> >
> > Modified:
> > forrest/trunk/site-author/content/xdocs/howto-dev.xml
> >
> > Modified: forrest/trunk/site-author/content/xdocs/howto-dev.xml
> > URL: http://svn.apache.org/viewvc/forrest/trunk/site-
> author/content/xdocs/howto-
> dev.xml?rev=437136&r1=437135&r2=437136&view=diff
> >
> ==========================================================================
> ====
> > --- forrest/trunk/site-author/content/xdocs/howto-dev.xml (original)
> > +++ forrest/trunk/site-author/content/xdocs/howto-dev.xml Sat Aug 26
> 02:44:52 2006
> > @@ -224,6 +224,63 @@
> > svn update -r HEAD.
> > </source>
> > </section>
> > + <section id="svn-merge">
> > + <title>Reverting Changes using SVN Merge</title>
> > + <p>You may want to revert some changes made to HEAD or may
> want to revert changes made
> > + to an earlier revision that still exists in HEAD
> today.</p>
> > + <p>This is where SVN Merge comes in handy. Taking the first
> scenario, here is an
> > + example of reverting a change from HEAD to an earlier
> revision 300.</p>
> > + <source>
> > +# reverting unneccesary changes to %FORREST_HOME%/site-
> author/content/xdocs/index.xml
> > +
> > +$ svn merge -r HEAD:300 /site-author/content/xdocs/index.xml /site-
> author/content/xdocs/index.xml
> > +
> > +# you should then get confirmation of this as :
> > +U /site-author/content/xdocs/index.xml
> > +
> > +# Then do an svn diff to verify the change is removed.
> > +$ svn diff
> > +...
> > +
> > +# Then commit the reverted changed file(s)
> > +
> > +$ svn commit -m "Undoing changes commited to index.xml in r300."
> > +Sending /site-author/content/xdocs/index.xml
> > +Transmitting file data .
> > +Committed revision 350.
> > + </source>
> > + <p>It should only be neccessary to specify a particular file
> to revert
> > + with svn merge only if there are other changed files
> in that revision.</p>
> > + <p> This second example assumes that way back in revision
> r303 only one change was
> > + made to one file and that this is what we want to
> remove.</p>
> > + <source>
> > +# reverting unneccessary change to /site-author/content/xdocs/index.xml
> > +# - this is the only changed file for this revision.
> > +
> > +svn merge -r 303:302
> > +
> > +# you should then get confirmation of this as "
> > +U index.xml
> > +
> > +# Then do an svn diff to verify the change is removed.
> > +$ svn diff
> > +...
> > +
> > +# Then commit the reverted changed file(s)
> > +
> > +$ svn commit -m "Undoing unwanted change to index.xml from r303."
> > +Sending index.xml
> > +Transmitting file data .
> > +Committed revision 351.
> > + </source>
> > + <p>The second example above will revert any changes made by
> revision 303
> > + from revision 302 and then applies it to the current
> revision HEAD which in
> > + this example has become r351. Also note that the
> changes have NOT been removed
> > + from ANY revisions in between r303 and r350, so
> rolling back to any of these
> > + revisions will add the un-needed change back in
> again.</p>
> > + <p> More information can be found at <a
> href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-
> 4.2">Common use-cases for
> > + merging</a> section of the Red Bean SVN
> Book.</p>
> > + </section>
> >
> > <section id="svn-patch">
> > <title>Creating patches</title>
> >
>
>
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.405 / Virus Database: 268.11.6/429 - Release Date: 8/28/2006
level of detail for docs (Was: svn commit: r437136)
Posted by David Crossley <cr...@apache.org>.
Why do we need this level of detail? Surely the "SVN Book"
explains it better than we can.
http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2
If not, then wouldn't it be better to submit a patch to that project.
Sorry if i appear to be jumping on your changes. I am trying
to use your early contributions to provide guidance.
My concerns are that the Forrest Project should not need
to maintain such documentation and rather concentrate on
Forrest topics. Our time gets wasted. For example, i detect
some obscurities in what you wrote.
Also the "tips for developers" document is becoming bloated.
Also ASF Committers should know how to do this stuff
or at least know to refer to the SVN Book.
-David
> Author: gmcdonald
> Date: Sat Aug 26 02:44:52 2006
> New Revision: 437136
>
> URL: http://svn.apache.org/viewvc?rev=437136&view=rev
> Log:
> Added in revert SVN changes section as per Jira Issue FOR-875
>
> Modified:
> forrest/trunk/site-author/content/xdocs/howto-dev.xml
>
> Modified: forrest/trunk/site-author/content/xdocs/howto-dev.xml
> URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/howto-dev.xml?rev=437136&r1=437135&r2=437136&view=diff
> ==============================================================================
> --- forrest/trunk/site-author/content/xdocs/howto-dev.xml (original)
> +++ forrest/trunk/site-author/content/xdocs/howto-dev.xml Sat Aug 26 02:44:52 2006
> @@ -224,6 +224,63 @@
> svn update -r HEAD.
> </source>
> </section>
> + <section id="svn-merge">
> + <title>Reverting Changes using SVN Merge</title>
> + <p>You may want to revert some changes made to HEAD or may want to revert changes made
> + to an earlier revision that still exists in HEAD today.</p>
> + <p>This is where SVN Merge comes in handy. Taking the first scenario, here is an
> + example of reverting a change from HEAD to an earlier revision 300.</p>
> + <source>
> +# reverting unneccesary changes to %FORREST_HOME%/site-author/content/xdocs/index.xml
> +
> +$ svn merge -r HEAD:300 /site-author/content/xdocs/index.xml /site-author/content/xdocs/index.xml
> +
> +# you should then get confirmation of this as :
> +U /site-author/content/xdocs/index.xml
> +
> +# Then do an svn diff to verify the change is removed.
> +$ svn diff
> +...
> +
> +# Then commit the reverted changed file(s)
> +
> +$ svn commit -m "Undoing changes commited to index.xml in r300."
> +Sending /site-author/content/xdocs/index.xml
> +Transmitting file data .
> +Committed revision 350.
> + </source>
> + <p>It should only be neccessary to specify a particular file to revert
> + with svn merge only if there are other changed files in that revision.</p>
> + <p> This second example assumes that way back in revision r303 only one change was
> + made to one file and that this is what we want to remove.</p>
> + <source>
> +# reverting unneccessary change to /site-author/content/xdocs/index.xml
> +# - this is the only changed file for this revision.
> +
> +svn merge -r 303:302
> +
> +# you should then get confirmation of this as "
> +U index.xml
> +
> +# Then do an svn diff to verify the change is removed.
> +$ svn diff
> +...
> +
> +# Then commit the reverted changed file(s)
> +
> +$ svn commit -m "Undoing unwanted change to index.xml from r303."
> +Sending index.xml
> +Transmitting file data .
> +Committed revision 351.
> + </source>
> + <p>The second example above will revert any changes made by revision 303
> + from revision 302 and then applies it to the current revision HEAD which in
> + this example has become r351. Also note that the changes have NOT been removed
> + from ANY revisions in between r303 and r350, so rolling back to any of these
> + revisions will add the un-needed change back in again.</p>
> + <p> More information can be found at <a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2">Common use-cases for
> + merging</a> section of the Red Bean SVN Book.</p>
> + </section>
>
> <section id="svn-patch">
> <title>Creating patches</title>
>