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 Daniel John Debrunner <dj...@debrunners.com> on 2006/08/14 19:20:54 UTC
How to commit documentation patches?
I was planning to commit some of the outstanding documentation patches,
e.g. DERBY-1548, but I realised I have no idea how to do this.
Looking at the download site there's no mention of the documentation
source code:
http://db.apache.org/derby/derby_downloads.html#Derby+source+code
I couldn't see anything in the wiki on how to download the svn source
for the documentation, build it (? I know it needs DITA, but that's
about all I know), and test it.
Seems like we could get documentation patches in quicker if all the
committers could handle them, rather than the the two or three who
submit these patches today. Let's scale with the size of the community.
Is there a write-up somewhere on how to do this?
Thanks,
Dan.
Re: How to commit documentation patches?
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Daniel John Debrunner wrote:
> Jean T. Anderson wrote:
>>Daniel John Debrunner wrote:
>>
>>>I was planning to commit some of the outstanding documentation patches,
>>>e.g. DERBY-1548, but I realised I have no idea how to do this.
>>
>>...
>>
>>>Is there a write-up somewhere on how to do this?
>>
>>Instructions are here:
>>
>>http://db.apache.org/derby/manuals/dita.html
>
> Thanks, never thought to look there.
maybe when the dust settles we can think about how to make it easier to
find all source. A pointer to the code source is on the downloads page,
pointer to the doc source on the documentation tab, pointer to the web
site source is on the community tab.
-jean
Re: How to commit documentation patches?
Posted by Daniel John Debrunner <dj...@apache.org>.
Jean T. Anderson wrote:
> Daniel John Debrunner wrote:
>
>>I was planning to commit some of the outstanding documentation patches,
>>e.g. DERBY-1548, but I realised I have no idea how to do this.
>
> ...
>
>>Is there a write-up somewhere on how to do this?
>
>
> Instructions are here:
>
> http://db.apache.org/derby/manuals/dita.html
Thanks, never thought to look there.
Dan.
Re: How to commit documentation patches?
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Daniel John Debrunner wrote:
> Jean T. Anderson wrote:
...
>>Instructions are here:
>>
>>http://db.apache.org/derby/manuals/dita.html
>
> In the section on "Editing DITA files" that page says:
>
> "Make sure to read the licenses for any XML editor you use to modify
> Derby DITA documentation."
>
> I'm sure there's some reason for reading the licences, my guess is to
> ensure the use of the tool does not place a restriction on the resulting
> XML file. Is that the case, should we be more explicit here?
Jeff wrote that -- actually he wrote most of this page, though I have
added a few fixes here and there.
-jean
Re: How to commit documentation patches?
Posted by Daniel John Debrunner <dj...@apache.org>.
Jean T. Anderson wrote:
> Daniel John Debrunner wrote:
>
>>I was planning to commit some of the outstanding documentation patches,
>>e.g. DERBY-1548, but I realised I have no idea how to do this.
>
> ...
>
>>Is there a write-up somewhere on how to do this?
>
>
> Instructions are here:
>
> http://db.apache.org/derby/manuals/dita.html
In the section on "Editing DITA files" that page says:
"Make sure to read the licenses for any XML editor you use to modify
Derby DITA documentation."
I'm sure there's some reason for reading the licences, my guess is to
ensure the use of the tool does not place a restriction on the resulting
XML file. Is that the case, should we be more explicit here?
Dan.
Re: How to commit documentation patches?
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Daniel John Debrunner wrote:
> I was planning to commit some of the outstanding documentation patches,
> e.g. DERBY-1548, but I realised I have no idea how to do this.
...
> Is there a write-up somewhere on how to do this?
Instructions are here:
http://db.apache.org/derby/manuals/dita.html
-jean
Re: How to commit documentation patches?
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
This thread got off on a tangent about editing DITA XML -- but
knowing/editing XML is not required for committing doc patches. You just
need to know svn and understand how to build the docs so you can verify
the doc build.
Also, my pointing Dan at the web site instructions [1] wasn't really
helpful. They do tell you how to check out the source, but don't say
specifically how to commit. --They were written from Jeff's viewpoint: a
patch contributor and a doc builder.
Below are instructions for committers that I'll add to that web page
when I have time.
1) Add these entries to your ~/.subversion/config file [2]:
*.dita = svn:eol-style=native
*.ditamap = svn:eol-style=native
2) Check out the doc source
svn checkout https://svn.apache.org/repos/asf/db/derby/docs/trunk/
3) The web site instructions [1] tell the patch creator to create the
patch at the trunk level, so download the patch to the trunk of your
local working copy.
4) If you're on linux and the patch is in Window format ....
dos2unix patch.diff
5) Apply the patch
patch -p0 < patch.diff
6) 'svn add' any files that need it
7) Verify the doc builds. The web site instructions [1] are good when it
comes to describing what to do to build the docs. All I check for is the
final message indicating success (don't want the automated nightly
builds to fail):
BUILD SUCCESSFUL
Total time: 4 minutes 24 seconds
8) Commit the changes.
Andrew, Halley, and Tomohito -- you have all committed changes to the
DITA docs. Can you think of anything that could be added?
Finally, if you have any problems, please open a Jira issue. Last
Spring Tomohito took the time to log DERBY-1269, which resulted in
improvements to [1]. Every little bit helps.
-jean
[1] http://db.apache.org/derby/manuals/dita.html
[2] http://www.apache.org/dev/svn-eol-style.txt
Re: Explanation of documentation file names (was :Re: How to commit
documentation patches?)
Posted by John Embretsen <Jo...@Sun.COM>.
Kristian Waagan wrote:
> There seems to be some prefixes:
> * 'c', 'r' and 't'.
> Not quite sure what these are.
These are explained here:
http://db.apache.org/derby/manuals/dita.html#DITA+file+names
"All DITA topics are classified as either concepts, tasks, or reference
material. Thus, every file begins with either a "c", "t", or "r". In
addition, the letters that appear immediately after this first one
provide a shorthand id for the manual. For example, the Getting Started
with Derby manual uses "gs", so a reference topic DITA file in that
manual will start with "rgs"."
> * 'dev', 'tools', 'tuning', 'ref'
> These indicate which manual the file belongs to.
>
> And, the great mystery, what do all the digits mean?
> Are they generated by a (deprecated) tool, are they random?
> For instance, 'rrefexcept71493.dita'.
On the same web page, I found:
"Subsequent letters in the file name may provide hints at the topic's
section within the manual, as well as numbers distinguishing it from
other DITA files."
It seems that the numbers are random, but perhaps someone with DITA- or
relevant historical knowledge has more details...
--
John
Re: Explanation of documentation file names (was :Re: How to commit documentation patches?)
Posted by Laura Stewart <sc...@gmail.com>.
Hi Kristian -
Answers below...
On 8/15/06, Kristian Waagan <Kr...@sun.com> wrote:
> Laura Stewart wrote:
> > As someone who has recently started to make contributions to the Derby
> > docs, I have found a few "holes" in what is written on that page.
> > After 10.2, I plan to make some updates to it, including proposing
> > some standards, and an explanation of the file names (yes they are
> > confusing :-)
>
> Hello Laura,
>
> I'm planning to take on a documentation task, which involves converting
> HTML files to the DITA XML format. I'm getting ready for that now, but I
> too don't understand the naming of the source files.
>
> There seems to be some prefixes:
> * 'c', 'r' and 't'.
> Not quite sure what these are.
*** (LS) These refer to the type of topic - concept, reference, and
task. Unfortunately there aren't any guidelines formally posted on
the Derby site as to the content for these. After 10.2 I hope to
propose some guidelines that we can all follow... if you need some
help before that time, just ask :-)
> * 'dev', 'tools', 'tuning', 'ref'
> These indicate which manual the file belongs to.
*** (LS) Yes. That is correct.
>
> And, the great mystery, what do all the digits mean?
> Are they generated by a (deprecated) tool, are they random?
> For instance, 'rrefexcept71493.dita'.
***(LS) I believe that these file names were generated when the
documentation was converted to DITA. That is before my time :-)
What I have adopted as a naming convention is to try to use general terms.
For example, I recently documented some new math functions.
Some of the existing names had numerical endings and some had the word
"func" at the end. The problem with putting "func" at the end is that
the files are then scattered all over the place. Instead I put the
"category" of info earlier in the name, so that the functions are all
together (at least the new ones that I added).
So I used the following:
r = reference topic
ref = Reference Manual
func = function
xxx = is the name of the actual function (sometimes abbreviated) and
it should unique
One of the functions was FLOOR, so the file name is rreffuncfloor.
>
> Can anyone please explain the naming scheme used for documentation
> source files?
>
*** (LS) I hope that this helps. There isn't a limitation in the
number of characters that you can use in a DITA file name... the names
should be unique. I use the xxx
to make the names unique.
--
Laura Stewart
Explanation of documentation file names (was :Re: How to commit
documentation patches?)
Posted by Kristian Waagan <Kr...@Sun.COM>.
Laura Stewart wrote:
> As someone who has recently started to make contributions to the Derby
> docs, I have found a few "holes" in what is written on that page.
> After 10.2, I plan to make some updates to it, including proposing
> some standards, and an explanation of the file names (yes they are
> confusing :-)
Hello Laura,
I'm planning to take on a documentation task, which involves converting
HTML files to the DITA XML format. I'm getting ready for that now, but I
too don't understand the naming of the source files.
There seems to be some prefixes:
* 'c', 'r' and 't'.
Not quite sure what these are.
* 'dev', 'tools', 'tuning', 'ref'
These indicate which manual the file belongs to.
And, the great mystery, what do all the digits mean?
Are they generated by a (deprecated) tool, are they random?
For instance, 'rrefexcept71493.dita'.
Can anyone please explain the naming scheme used for documentation
source files?
Thanks,
--
Kristian
>
> I am not a committer so I would need someone who is to help me
> understand the steps required for committing doc info so that I can
> write that up for the community.
Re: How to commit documentation patches?
Posted by Laura Stewart <sc...@gmail.com>.
On 8/14/06, Daniel John Debrunner <dj...@apache.org> wrote:
(begin snip)
> Now it seems there are three possible choices for a committer:
>
> A) commit the patch without any further review
> + gets the patch submitted the quickest
> + allows more eyes on the change early
> - chance for wrong information applied to docs
>
> B) reviewer the patch themselves and then commit
> + almost as good as 1) on the time frame
> - extra time committment by a committer
> +/- less chance for wrong information (depends on if committer
> knows the area)
>
> C) wait for an additional review (by anyone) [Jean's approach]
> + least chance for wrong information (but still a chance)
> - longer timeframe before committing
> * initial reviewer may not have time to review the revised patch
> * other reviewers may not appear
>
(end snip)
As a person interested in the documentation, this problem is a concern to me.
Ideally I prefer C because it assures me that another review will
validate the changes. More importantly, sometimes I have questions
about a change or reasons why I wordsmithed a proposed change and I
would prefer another person validate that my wordsmithing doesn't
change the meaning of the content... inotherwords does not make the
docs technically inaccurate.
However there are times when a small or simple change could be
committed immediately.
One possible option is to flag the issue to indicate that it is minor
or significant and let that flag dictate the approach taken by
committers...
--
Laura Stewart
Re: How to commit documentation patches?
Posted by Daniel John Debrunner <dj...@apache.org>.
Jean T. Anderson wrote:
> Daniel John Debrunner wrote:
>
>>Jean T. Anderson wrote:
>
> ...
>
>>>Of course, any other committer is also welcome to jump in, but it looks
>>>to me like everyone is massively busy.
>>
>>This is a problem for the community, we need more than just Jean to
>>commit documentation patches. That's why I started looking at getting
>>setup, I hope other committers do the same.
>
>
> Jean is not the only one who commits patches to the doc tree. Andrew,
> Halley, and Tomohito have all committed changes to the doc tree. --And
> there might be more that I have missed.
Yes I had the wrong impression, having got the svn trunk for the docs I
now see other committers have committed patches and/or documentation.
Sorry,
Dan.
Re: How to commit documentation patches?
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Daniel John Debrunner wrote:
> Jean T. Anderson wrote:
...
>>Of course, any other committer is also welcome to jump in, but it looks
>>to me like everyone is massively busy.
>
> This is a problem for the community, we need more than just Jean to
> commit documentation patches. That's why I started looking at getting
> setup, I hope other committers do the same.
Jean is not the only one who commits patches to the doc tree. Andrew,
Halley, and Tomohito have all committed changes to the doc tree. --And
there might be more that I have missed.
But, the real answer is any committer really can commit a doc patch (it
doesn't require knowing or editing DITA XML) and I hope this followup
post convinces committers that committing doc patches is very much like
committing code patches:
http://mail-archives.apache.org/mod_mbox/db-derby-dev/200608.mbox/%3c44E0E29C.50903@bristowhill.com%3e
The doc verification step is different -- and quite a bit easier than
code verification imho.
-jean
Re: How to commit documentation patches?
Posted by Daniel John Debrunner <dj...@apache.org>.
Jean T. Anderson wrote:
> So far the process has been pretty ad hoc. Last week I offered to do
> 10.2 doc commits [1]:
>
>
>>I'll volunteer to keep these on my radar. If reviewers will please add a
>>comment to the Jira issue that the patch is good to go (or not), I'll
>>then commit the ones that are ready.
> Of course, any other committer is also welcome to jump in, but it looks
> to me like everyone is massively busy.
This is a problem for the community, we need more than just Jean to
commit documentation patches. That's why I started looking at getting
setup, I hope other committers do the same.
> The main thing I'm looking for is a clear comment in Jira that indicates
> a patch is ready to commit. There are *lots* of doc patches and I don't
> have time to review them; I'm relying on technically knowledgeable
> reviewers to indicate a patch is ready.
Seems a reasonable approach given "with a commit-then-review process,
the Committer is trusted to have a high degree of confidence in the change".
I wonder though how a committer should handle a typical exchange like
this for a doc change:
- patch submitted
- reviewer makes comments
- revised patch
Now it seems there are three possible choices for a committer:
A) commit the patch without any further review
+ gets the patch submitted the quickest
+ allows more eyes on the change early
- chance for wrong information applied to docs
B) reviewer the patch themselves and then commit
+ almost as good as 1) on the time frame
- extra time committment by a committer
+/- less chance for wrong information (depends on if committer
knows the area)
C) wait for an additional review (by anyone) [Jean's approach]
+ least chance for wrong information (but still a chance)
- longer timeframe before committing
* initial reviewer may not have time to review the revised patch
* other reviewers may not appear
I think the choice can depend on the changes in the last patch. With a
revised patch that just fixes a spelling mistake noticed by a reviewer,
it seems A) is better. With a revised patch that re-works a whole
concept, e.g. "authorization" to "connection access", another review is
probably justified.
I believe though the two advantages for A) outweigh the chance of wrong
information being committed due to lack of that final review, the
problems will get picked up at one point. Of course this is good for the
trunk, maybe not a release branch.
Of course C) could be speeded up if we had more reviewers, maybe
contributors interested in documentation who want to gain merit could
help out by reviewing doc patches. Especially while they are in this
final phase (all review comments addressed), Jean (or other committers)
waiting for the final stamp of approval.
Believe it or not, I've tried to work more towards A) in committing code
changes, if the code works, passes the test then commit it even if it
isn't perfect. The imperfections can be logged and worked on later, e.g.
better factoring, more comments etc. Get more eyes & testers on the code
earlier. I do have a threshold though, if all the tests pass but the
code approach seems to take Derby internally in the wrong direction then
I like to see the changes up front.
Dan.
Re: How to commit documentation patches?
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Laura Stewart wrote:
> As someone who has recently started to make contributions to the Derby
> docs, I have found a few "holes" in what is written on that page.
> After 10.2, I plan to make some updates to it, including proposing
> some standards, and an explanation of the file names (yes they are
> confusing :-)
excellent! Improvements are always welcome.
> I am not a committer so I would need someone who is to help me
> understand the steps required for committing doc info so that I can
> write that up for the community.
this would be excellent to writeup as well.
So far the process has been pretty ad hoc. Last week I offered to do
10.2 doc commits [1]:
> I'll volunteer to keep these on my radar. If reviewers will please add a
> comment to the Jira issue that the patch is good to go (or not), I'll
> then commit the ones that are ready.
Of course, any other committer is also welcome to jump in, but it looks
to me like everyone is massively busy.
The main thing I'm looking for is a clear comment in Jira that indicates
a patch is ready to commit. There are *lots* of doc patches and I don't
have time to review them; I'm relying on technically knowledgeable
reviewers to indicate a patch is ready. For example, Deepa's comment in
DERBY-1057 [2] is *perfect* (thanks, Deepa!):
> Thanks Laura for addressing my comments. I looked at the updated html file "rtunpropersqlauth.html" for tuning guide and it looks good to me. My +1 to commit this patch "derby1057_tuning4.diff".
I especially appreciate Deepa including the name of the patch file in
her comment. Some of the Jira issues, such as DERBY-1057, have so many
patches it can get kind of confusing.
Once the 10.2 dust settles, maybe we can work out consistent procedures
for us all to follow. --And also improve the instructions so any
committer feels comfortable committing doc patches.
btw, Laura, you're doing a terrific job and I appreciate it. You, too, Kim!
-jean
[1]
http://mail-archives.apache.org/mod_mbox/db-derby-dev/200608.mbox/%3c44DA54CF.9020602@bristowhill.com%3e
[2] http://issues.apache.org/jira/browse/DERBY-1057#action_12427289
Re: How to commit documentation patches?
Posted by Laura Stewart <sc...@gmail.com>.
As someone who has recently started to make contributions to the Derby
docs, I have found a few "holes" in what is written on that page.
After 10.2, I plan to make some updates to it, including proposing
some standards, and an explanation of the file names (yes they are
confusing :-)
I am not a committer so I would need someone who is to help me
understand the steps required for committing doc info so that I can
write that up for the community.
--
Laura Stewart
Re: How to commit documentation patches?
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
David Van Couvering wrote:
...
> I think those in the docs area who are tired of checking in other
> people's changes perhaps might be motivated to write a tutorial showing
> how to do this, and to provide a single recommendation for a good *free*
> DITA editor. :)
If anyone has time to produce a tutorial (even an initial, not-so-spiffy
tutorial), that'd be great.
I don't think a single recommendation will work because we're all in
different operating environments and familiar with different tools. But
I did post about 3 XML editors back in May [1].
That much said, I keep reverting to vi.
-jean
[1]
http://www.nabble.com/-web---doc--3-tools-for-editing-Derby-Web-site-XML-source-p4653789.html
Re: How to commit documentation patches?
Posted by David Van Couvering <Da...@Sun.COM>.
This is definitely a start. But when I looked at making my own changes
to the DITA files, it made my head spin. There are all these files with
strange names, and no real clear idea how they all fit together. Then
you have to purchase or download a DITA editor (with no clear
recommendation, just a list of options, many of them having a cost), or
edit in raw XML. The whole thing is a bit mystifying to me.
I understand the value of being able to generate HTML and PDF documents.
But it really impacts the ability for a novice to update the
documentation.
I think those in the docs area who are tired of checking in other
people's changes perhaps might be motivated to write a tutorial showing
how to do this, and to provide a single recommendation for a good *free*
DITA editor. :)
David
Andrew McIntyre wrote:
> On 8/14/06, Daniel John Debrunner <dj...@debrunners.com> wrote:
>>
>> I was planning to commit some of the outstanding documentation patches,
>> e.g. DERBY-1548, but I realised I have no idea how to do this.
>>
>> Looking at the download site there's no mention of the documentation
>> source code:
>> http://db.apache.org/derby/derby_downloads.html#Derby+source+code
>>
>> I couldn't see anything in the wiki on how to download the svn source
>> for the documentation, build it (? I know it needs DITA, but that's
>> about all I know), and test it.
>>
>> Seems like we could get documentation patches in quicker if all the
>> committers could handle them, rather than the the two or three who
>> submit these patches today. Let's scale with the size of the community.
>>
>> Is there a write-up somewhere on how to do this?
>
> There is this page, which should describe most of what you need:
>
> http://db.apache.org/derby/manuals/dita.html
>
> It's hiding in the drop-down box off the left when you click the
> Documentation tab as "DITA source". I think a link from the main
> documentation page might help make this easier to find.
>
> andrew
Re: Difficulty finding source + instructions (Was Re: How to commit documentation patches?)
Posted by Laura Stewart <sc...@gmail.com>.
On 8/15/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
> Information about source is spread out -- code source on the downloads
> page, doc source on the documentation tab, web site source on the
> community tab ....
>
> We could really use one page on "Derby Source" with info (or pointers)
> to all three, especially since svn info and tips could be consolidated
> for all three.
>
> -jean
>
*** (LS) I agree, it would be very useful to have the info/tips
consolidated and then links to the various source pages.
--
Laura Stewart
Difficulty finding source + instructions (Was Re: How to commit documentation
patches?)
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
John Embretsen wrote:
...
> One thing I noticed the first time I wanted to contribute a doc patch,
> was that on the "Community" tab/page [1], I found no mention of
> documentation source, patches, or links to relevant doc information in
> the section called "Contribute Code or Documentation". The information
> there is very code-centric, as are the various wiki pages that are
> linked to from that page.
Information about source is spread out -- code source on the downloads
page, doc source on the documentation tab, web site source on the
community tab ....
We could really use one page on "Derby Source" with info (or pointers)
to all three, especially since svn info and tips could be consolidated
for all three.
-jean
Re: How to commit documentation patches?
Posted by John Embretsen <Jo...@Sun.COM>.
Andrew McIntyre wrote:
> On 8/14/06, Daniel John Debrunner <dj...@debrunners.com> wrote:
[SNIP]
>> Seems like we could get documentation patches in quicker if all the
>> committers could handle them, rather than the the two or three who
>> submit these patches today. Let's scale with the size of the community.
>>
>> Is there a write-up somewhere on how to do this?
>
> There is this page, which should describe most of what you need:
>
> http://db.apache.org/derby/manuals/dita.html
>
> It's hiding in the drop-down box off the left when you click the
> Documentation tab as "DITA source". I think a link from the main
> documentation page might help make this easier to find.
I agree, it is too hard to find the information you need when you want
to become a new doc contributor or committer.
One thing I noticed the first time I wanted to contribute a doc patch,
was that on the "Community" tab/page [1], I found no mention of
documentation source, patches, or links to relevant doc information in
the section called "Contribute Code or Documentation". The information
there is very code-centric, as are the various wiki pages that are
linked to from that page.
--
John
[1]
http://db.apache.org/derby/derby_comm.html#Contribute+Code+or+Documentation
Re: How to commit documentation patches?
Posted by Andrew McIntyre <mc...@gmail.com>.
On 8/14/06, Daniel John Debrunner <dj...@debrunners.com> wrote:
>
> I was planning to commit some of the outstanding documentation patches,
> e.g. DERBY-1548, but I realised I have no idea how to do this.
>
> Looking at the download site there's no mention of the documentation
> source code:
> http://db.apache.org/derby/derby_downloads.html#Derby+source+code
>
> I couldn't see anything in the wiki on how to download the svn source
> for the documentation, build it (? I know it needs DITA, but that's
> about all I know), and test it.
>
> Seems like we could get documentation patches in quicker if all the
> committers could handle them, rather than the the two or three who
> submit these patches today. Let's scale with the size of the community.
>
> Is there a write-up somewhere on how to do this?
There is this page, which should describe most of what you need:
http://db.apache.org/derby/manuals/dita.html
It's hiding in the drop-down box off the left when you click the
Documentation tab as "DITA source". I think a link from the main
documentation page might help make this easier to find.
andrew