crossley 02/05/17 05:37:26
Modified: src/documentation/xdocs/howto book.xml index.xml
Added: src/documentation/xdocs/howto howto-bugzilla.xml
Log:
Added draft "How to Contribute a Patch via Bugzilla".
Revision Changes Path
1.2 +4 -4 xml-cocoon2/src/documentation/xdocs/howto/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 13 May 2002 18:00:48 -0000 1.1
+++ book.xml 17 May 2002 12:37:26 -0000 1.2
@@ -17,9 +17,9 @@
<menu-item label="Author How-to" href="howto-author-howto.html"/>
<menu-item label="Author FAQ" href="howto-author-faq.html"/>
</menu>
-
-
+ <menu label="Contribution">
+ <menu-item label="Bugzilla" href="howto-bugzilla.html"/>
+ </menu>
+
</book>
-
-
1.2 +9 -1 xml-cocoon2/src/documentation/xdocs/howto/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 13 May 2002 18:00:48 -0000 1.1
+++ index.xml 17 May 2002 12:37:26 -0000 1.2
@@ -15,7 +15,7 @@
<s1 title="Overview">
<p>
-This is a collection of How-tos. The Cocooon project is actively seeking additional
How-to contributors to expand this collection. For information on how to write your
own How-to, please see <link href="howto-author-howto.html">How to write your own
How-to.</link>
+This is a collection of How-tos. The Cocooon project is actively seeking additional
How-to contributors to expand this collection. For information on how to do that,
please see <link href="howto-author-howto.html">How to write a How-to</link>.
</p>
@@ -26,6 +26,14 @@
<li><link href="howto-author-faq.html">How to Write an FAQ</link></li>
</ul>
+ </s2>
+
+ <s2 title="Contribution How-Tos">
+
+ <ul>
+<li><link href="howto-bugzilla.html">How to Contribute a Patch
+via Bugzilla</link></li>
+ </ul>
</s2>
<s2 title="Third Party HOWTOs">
1.1 xml-cocoon2/src/documentation/xdocs/howto/howto-bugzilla.xml
Index: howto-bugzilla.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>How to Contribute a Patch via Bugzilla</title>
<version>0.1</version>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
Bugzilla is the Internet-based mechanism to facilitate contributions to any
Apache project. This includes changes to code and changes to documents
(Patches), and also reports of bugs and suggestions for enhancement.
In this How-to, we are concentrating on providing a Patch. Perhaps another
How-to will describe adding a full Bug report, though this document will get
you started.
</p>
<p>
We will explain how to create your Bugzilla account, how to enter a patch
description, and finally how to attach the actual patch file.
</p>
</s1>
<s1 title="Intended Audience">
<p>
This document is meant for first-time users.
The Bugzilla interface can be daunting, so this is a concise explanation of
how to start. Once you can do that, you can proceed to make more substantial
contributions. Of course, it concentrates only on Cocoon contributions.
</p>
</s1>
<s1 title="Prerequisites">
<p>
Bugzilla contributors should:
</p>
<ul>
<li>Understand what a Patch is and how to make one.
<!-- See <link href="howto-patch.html">How to Prepare a Patch</link> -->
See <link href="">How to Prepare a Patch</link> (Doc under development).
Note that a new complete document is still just a patch.
</li>
<li>Understand that Bugzilla is the Apache Bug Database. Bugzilla does not
distinguish between a Bug report, a Patch submission, and an Enhancement suggestion.
They are all <em>"Bugs"</em> as far as Bugzilla is concerned.
</li>
</ul>
</s1>
<s1 title="Steps">
<p>
Here is how to proceed. Go to
<fork href="http://nagoya.apache.org/bugzilla/";>Bugzilla</fork>
in another browser window.
</p>
<s2 title="1. Open a Bugzilla Account" >
<p>
Follow the online instructions from the home page. Do not worry, you will
not be sent spam email nor bombarded with advertisements.
</p>
<p>
Note that you can conduct queries in Bugzilla and review submissions without
having an account. However, to make a contribution you must have an account.
This ensures legitimacy. It also enables the system to automatically send you
email when your patch is applied by a Cocoon committer.
</p>
</s2>
<s2 title="2. Enter a new bug report" >
<p>
Choose that link from the Bugzilla home page. You will be asked to first
select the relevant project ... choose Cocoon 2 of course. Next you will be
asked to provide your account details. Following that you will be presented
an input form for the various details ...
</p>
</s2>
<s2 title="3. Specify Version" >
<p>
This is the version of Cocoon that you prepared your patch against. Use the
default <code>Current CVS</code> if you have an up-to-date local working copy
of HEAD branch or a very recent nightly build. Otherwise choose the relevant
release version.
</p>
</s2>
<s2 title="4. Specify Component" >
<p>
Follow the "Component" link for description of the available
components. If you do not know which component then just use <code>core</code>.
</p>
</s2>
<s2 title="5. Specify Platform" >
<p>
Really meant for bug reporting. Perhaps it could be relevant for a patch.
You would usually specify the <code>All</code> option.
</p>
</s2>
<s2 title="6. Specify Operating System" >
<p>
Really meant for bug reporting. Perhaps it could be relevant for a patch.
You would usually specify the <code>All</code> option.
</p>
</s2>
<s2 title="7. Specify Severity" >
<p>
The impact that would arise from not applying the patch. For a documentation
patch, the severity would usually be the default <code>Normal</code>.
However, if it addressed some serious lack or fixed a misguided configuration
statement, then the impact could be <code>major</code>.
</p>
<p>
(The <code>enhancement</code> option would not be used for a patch, as it is
intended for suggesting something that should be done. Use this wisely. It
would be better to discuss it on the mailing list first, and when clear then
describe it.)
</p>
</s2>
<s2 title="8. Specify Initial State" >
<p>
Use the <code>New</code> option.
</p>
</s2>
<s2 title="9. Specify Assigned To" >
<p>
Leave it blank. It will be automatically assigned to the
<code>cocoon-dev</code> mailing list. When a committer takes on your patch,
they will assign the bug to themselves. This pevents duplication of effort by
other committers.
</p>
<p>
The Cc field can be used if you need to have the bug reports, and any
follow-up, copied to some other person. Remember that the posting will get
automatically sent to the <code>cocoon-dev</code> mailing list, so no need to
Cc anyone there.
</p>
</s2>
<s2 title="9. Specify URL" >
<p>
If the patch refers to a particular document, then provide the website URL.
If it a refers to an issue with one of the local Cocoon Samples, then provide
the localhost URL.
</p>
</s2>
<s2 title="9. Carefully choose the Summary" >
<p>
This will become the all-important title of the bug. Use it wisely. You want
to draw attention to your patch. Just as with posting email to the listervers,
if you choose a poor title then your posting can be easily overlooked.
Use up all the characters available ... about 60 maximum.
</p>
<p>
Start the Summary with the <code>[PATCH]</code> tag. This will enable the
Cocoon automated patch queue summary to the mailing lists to remind people what
patches are pending. If you do not do this then your patch could easily be
overlooked.
</p>
</s2>
<s2 title="10. Description" >
<p>
Provide a brief explanation of what your patch does. Supply any instructions
to help the committer apply your patch efficiently. Note any issues that may
remain. It may help to list each file that you are submitting and briefly
describe what it is.
</p>
<p>
The committer will need to provide a descriptive log message when they commit
your work. Your clear description will help them.
</p>
<p>
You might already have the Description and Summary text written before you
start entering the patch report. Perhaps save it in a local text file
beforehand, and then copy-and-paste it when the time comes.
</p>
<p>
If this was a bug report, then it would need extensive description.
</p>
</s2>
<s2 title="11. Send the patch report" >
<p>
Review your options, then press the <strong>Commit</strong> button. This will
add an entry to the bug database and send email to the
<code>cocoon-dev</code> mailing list and a copy to you. Your submission will be
assigned a unique Bug Number which you can use to review its progress.
</p>
<p>
The next steps will show you how to attach your patch to the report that you
have just created ...
</p>
</s2>
<s2 title="12. Create an attachment of the actual patch" >
<p>
You will be presented with a status screen saying that your bug report
was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
</p>
<p>
Now you have a choice ... proceed to review your bug report by selecting the
link "Back to Bug #XXXXX". If you forgot to mention something,
then you can add more comments. From that screen you can follow the link
"Create a new attachment".
</p>
<p>
Otherwise follow the link from this status screen to "Attach a file to
this bug".
</p>
</s2>
<s2 title="13. Specify the file to be uploaded" >
<p>
Provide the local pathname to your patchfile, e.g.
<code>/home/me/work/cocoon/patch/howto-bugzilla.tar.gz</code>
</p>
</s2>
<s2 title="14. Describe the attachment" >
<p>
Provide a concise one line description, e.g.
<code>Gzipped TAR archive with new docs and diffs</code>
</p>
</s2>
<s2 title="15. Specify the contentType of the attachment" >
<p>
If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then select
"<code>Binary file (application/octet-stream)</code>".
If it is just a single xml document, then select
"<code>Plain text (text/plain)</code>".
If the patch is just a single diff file, then select
"<code>Patch file (text/plain, diffs)</code>".
</p>
</s2>
<s2 title="15. Submit the attachment" >
<p>
When you are ready, press the <strong>Submit</strong> button. As for Step 11,
you will be presented with a status screen saying that your attachment
was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
</p>
</s2>
<s2 title="16. Be patient" >
<p>
Now your patch will wait inside Bugzilla, until one of the Cocoon committers
assigns the patch to themselves and starts to process it and apply it to the
master CVS repository. You will be sent automatic email at each of these stages
because you are the registered owner of the Bug.
</p>
</s2>
<s2 title="17. Add more description or attachments if necessary" >
<p>
Until the patch is applied by the committer and the Bug report is closed, you
can still add more to your bug report. However, only do this if it is
absolutely necessary because the committer does not want the patch to be
changing while they are trying to commit it. If it is just further changes
that you want to make, then it would be better to wait until your patch is
applied. Then you can make a new patch. Remember that the committer has full
veto and may decide to make some slight modifications to your patch. So it
is far better to wait.
</p>
</s2>
<s2 title="18. Adding subsequent patches to the same document or program" >
<p>
If you want to make more patches to the same file, then please open a new Bug
rather than re-open the old one. After all, the original patch is already
applied by the committer and the Bug report is closed.
</p>
</s2>
</s1>
<s1 title="Extension">
<note>Author note: Help ... not sure what the
<strong>extension</strong> section is for.</note>
</s1>
<s1 title="Tips">
<s2 title="Setting user preferences">
<p>
You can configure certain preferences, though the Bugzilla defaults work just
fine.
</p>
</s2>
<s2 title="Review the bugzilla documentation">
<p>
There are various explanations of terminology and procedures ... follow the
links should you need to know more.
</p>
</s2>
<s2 title="Search Bugzilla">
<p>
There is a very powerful search interface. Now that you have a login account,
Bugzilla can remember your specific queries and you can run them with a click.
</p>
</s2>
</s1>
<s1 title="References">
<ul>
<li>
Bugzilla is at
<link
href="http://nagoya.apache.org/bugzilla/";>http://nagoya.apache.org/bugzilla/</link>
</li>
<li>
There are very helpful Bug Writing Guidelines available directly from the
Bug entry interface.
</li>
</ul>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
