nicko 2005/04/24 16:51:22
Modified: xdocs/src contributing.xml
doc contributing.html
Log:
Added section on contributing patches via JIRA
Revision Changes Path
1.7 +115 -3 logging-log4net/xdocs/src/contributing.xml
Index: contributing.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/contributing.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- contributing.xml 11 Mar 2005 23:03:21 -0000 1.6
+++ contributing.xml 24 Apr 2005 23:51:22 -0000 1.7
@@ -26,6 +26,8 @@
<body>
<section name="Contributing to log4net Development">
+ <sectionMenu name="Contents" />
+
<!--
<p>
blah blah mailing list, cvs, issues, blah
@@ -134,6 +136,12 @@
server. To do so, simply use
the following commands (if you are
using a GUI CVS client,
configure it appropriately).
</p>
+ <p>
+ Please ensure that your CVS
client is operating in UNIX mode. This
+ is the mode where the client
does <i>not</i> translate UNIX style newlines
+ into DOS style carriage
return/linefeeds. Failing to do this will cause
+ compile errors in the log4net
code.
+ </p>
<p>
First login to the CVS server
as the anonymous user.
@@ -215,19 +223,123 @@
<li><b>Stack Traces</b> - Any
stack traces generated by the bug, if any.</li>
<li><b>Example</b> - Example
configuration files or web applications which demonstrate the bug. When
submitting an example which reproduces the bug, please try to make it as simple
as possible.</li>
<li><b>Bug Fix Patch</b> - A
patch created using <span class="code">diff -u</span> which fixes the bug. (If
you have found a bug fix which can be applied to the code).</li>
- <li><b>Description of the
Bug</b> - A description of the bug, include observed as well as expected
behaviour.</li>
+ <li><b>Description of the
Bug</b> - A description of the bug, include observed as well as expected
behavior.</li>
<li><b>Miscellaneous</b> - Any
other information you feel will help track down the problem.</li>
</ul>
<p>
<b>Just reporting a bug will
not fix it. A good bug report includes a detailed description of the
- problem and a succinct test
case which can reproduce the problem.</b>
+ problem and a succinct test
case which can reproduce the problem.</b> The very best sort of report
+ includes an NUnit testcase
which reproduces the issue, this means that we can fix it and that we can
+ be sure that it stays fixed in
future!
</p>
<p>
- <a
href="http://issues.apache.org/jira/browse/LOG4NET";>Report a log4net bug</a>.
+ <a
href="http://issues.apache.org/jira/browse/LOG4NET";>Report a log4net issue
here</a>. You will need to login to JIRA before you can submit an issue.
</p>
</section>
</section>
+ <section name="Contributing Patches">
+ <p>
+ Before starting to work on a patch it
is probably a good idea to join the log4net-dev
+ mailing list to check that equivalent
or complementary work is not already underway.
+ </p>
+ <p>
+ Currently the only supported way of
submitting patches to log4net
+ is via the JIRA issue tracking system.
+ </p>
+ <p>
+ The preferred method of generating a
patch is a unified context diff against
+ the latest development version in CVS.
To do this you should do the following:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Get the latest version
of the code from CVS, see the section above on
+ <i>Anonymous CVS
Access</i> for details on how to obtain the CVS version.
+ </p>
+ </li>
+ <li>
+ <p>
+ Make your code changes
to the log4net source. Please follow existing
+ code styles where
possible. If adding new API methods or classes then
+ these should be
appropriately documented with code comments.
+ Contributions intended
for inclusion in ASF products must be licensed
+ to ASF under the terms
of the
+ <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache Software License</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a unified
context diff for the files you have changed. Run the
+ <span class="code">cvs
diff -u > patch-file</span> command from the root of the log4net
+ codebase to generate a
diff file.
+ </p>
+ </li>
+ <li>
+ <p>
+ If you have added new
files these will not be included in the diff. You
+ will need to attach
these files separately.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If you are not using CVS then you can
still generate a unified context diff
+ using the <i>diff</i> GNU tool. The GNU
tools are available for Windows as part
+ of the <a
href="www.cygwin.com">Cygwin</a> package.
+ </p>
+ <p>
+ If you are unable to generate a diff
please submit each file separately and place
+ block comments around each code change
to highlight the differences.
+ </p>
+
+ <p>
+ In order to submit your patch please
follow the following steps:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Create a new issue for
your patch. On the
+ <a
href="http://issues.apache.org/jira/browse/LOG4NET";>log4net issues home page</a>
+ select the <i>Create
New Issue</i> from the menu bar. You will need to be logged
+ into JIRA in order to
create an issue.
+ </p>
+ </li>
+ <li>
+ <p>
+ Select the issue type
as appropriate.
+ </p>
+ </li>
+ <li>
+ <p>
+ Prefix the summary with
<b>[PATCH]</b>. Enter a description of the changes made,
+ new features, or bug
fixes in your patch.
+ </p>
+ </li>
+ <li>
+ <p>
+ Once the issue has been
created you can attach your patch file to the issue
+ by selecting the
<i>Attach file to this issue</i> operation from the left hand
+ menu. When attaching
your patch you must select the <b>Grant license to ASF for
+ inclusion in ASF
works</b> option. If attaching a patch please include in the
+ description the
baseline version of log4net you used to build your patch, if against
+ a CVS version please
include the date and branch (e.g. HEAD).
+ </p>
+ </li>
+ <li>
+ <p>
+ If you have other files
to attach, e.g. you have added new files to log4net, then
+ attach each file
separately. Please include in the description the name of the file
+ attached and the path
it should live in the project.
+ </p>
+ </li>
+ </ul>
+ <p>
+ A notification will be sent to the
log4net-dev list once you have created your issue,
+ however it may also be worth mailing
the log4net-dev list to encourage the project
+ committers to apply your patch, or at
least find out when they may do so.
+ </p>
+ </section>
+
<!-- TODO: Add guidelines for contributors
<section name="Guidelines for Contributors">
<p>
1.8 +159 -14 logging-log4net/doc/contributing.html
Index: contributing.html
===================================================================
RCS file: /home/cvs/logging-log4net/doc/contributing.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- contributing.html 11 Mar 2005 23:03:21 -0000 1.7
+++ contributing.html 24 Apr 2005 23:51:22 -0000 1.8
@@ -65,15 +65,51 @@
<!-- START main table -->
-
<h1><a id="HC-16711231"></a>Contributing to log4net Development</h1>
+
<h1><a id="HC-23894119"></a>Contributing to log4net Development</h1>
<div class="i1">
- <h2><a
id="HC-28441588"></a>Developer Mailing List</h2>
+ <h2>Contents</h2>
+ <div class="i1">
+
<a
href="#HC-29154294">Developer Mailing List</a><br/>
+ <div class="i1">
+ <a
href="#HC-1117233">Mailing List Archives</a><br/>
+ <div class="i1">
+ </div>
+ <a
href="#HC-14707008">Subscribe</a><br/>
+ <div class="i1">
+ </div>
+ <a
href="#HC-19147537">Unsubscribe</a><br/>
+ <div class="i1">
+ </div>
+ <a
href="#HC-25657668">Posting</a><br/>
+ <div class="i1">
+
</div>
+ </div>
+
<a href="#HC-9956845">CVS
Access</a><br/>
+ <div class="i1">
+ <a href="#HC-8752113">Browsing
CVS</a><br/>
+ <div class="i1">
+ </div>
+ <a
href="#HC-27692793">Anonymous CVS Access</a><br/>
+ <div class="i1">
+
</div>
+ </div>
+
<a
href="#HC-32801378">Issue Tracking</a><br/>
+ <div class="i1">
+
<a href="#HC-26999600">Reporting an Issue</a><br/>
+ <div class="i1">
+
</div>
+ </div>
+
<a
href="#HC-25706868">Contributing Patches</a><br/>
+ <div class="i1">
+
</div>
+ </div>
+ <h2><a
id="HC-29154294"></a>Developer Mailing List</h2>
<div class="i1">
<p>
All discussion relating to log4net
development takes place on this list. All CVS checkin
notifications are also copied to this
list.
</p>
- <h3><a
id="HC-4300037"></a>Mailing List Archives</h3>
+ <h3><a
id="HC-1117233"></a>Mailing List Archives</h3>
<div class="i1">
<p>
You can browse the mailing list
archives at the following locations:
@@ -85,7 +121,7 @@
<li><a
href="http://sourceforge.net/mailarchive/forum.php?forum=log4net-devel";>Old
Mailing List at sourceforge</a></li>
</ul>
</div>
- <h3><a
id="HC-8344960"></a>Subscribe</h3>
+ <h3><a
id="HC-14707008"></a>Subscribe</h3>
<div class="i1">
<p>
Subscribe to either the list or
to the digest list:
@@ -106,7 +142,7 @@
</li>
</ul>
</div>
- <h3><a
id="HC-29775659"></a>Unsubscribe</h3>
+ <h3><a
id="HC-19147537"></a>Unsubscribe</h3>
<div class="i1">
<p>
To unsubscribe send an email to
the relevant email address:
@@ -127,7 +163,7 @@
</li>
</ul>
</div>
- <h3><a
id="HC-8702985"></a>Posting</h3>
+ <h3><a
id="HC-25657668"></a>Posting</h3>
<div class="i1">
<p>
Most of the guidelines for the
log4net-user list also apply to the dev list.
@@ -148,16 +184,16 @@
</p>
</div>
</div>
- <h2><a
id="HC-7314318"></a>CVS Access</h2>
+ <h2><a
id="HC-9956845"></a>CVS Access</h2>
<div class="i1">
- <h3><a id="HC-6775863"></a>Browsing
CVS</h3>
+ <h3><a id="HC-8752113"></a>Browsing
CVS</h3>
<div class="i1">
<p>
<a
href="http://cvs.apache.org/viewcvs/logging-log4net/";>Browse log4net</a>
CVS repository using ViewCVS.
</p>
</div>
- <h3><a
id="HC-31753535"></a>Anonymous CVS Access</h3>
+ <h3><a
id="HC-27692793"></a>Anonymous CVS Access</h3>
<div class="i1">
<p>
Anyone can checkout source code
from our anonymous CVS
@@ -165,6 +201,12 @@
using a GUI CVS client,
configure it appropriately).
</p>
<p>
+ Please ensure that your CVS
client is operating in UNIX mode. This
+ is the mode where the client
does <i>not</i> translate UNIX style newlines
+ into DOS style carriage
return/linefeeds. Failing to do this will cause
+ compile errors in the log4net
code.
+ </p>
+ <p>
First login to the CVS server
as the anonymous user.
</p>
@@ -186,7 +228,7 @@
</p>
</div>
</div>
- <h2><a
id="HC-30752603"></a>Issue Tracking</h2>
+ <h2><a
id="HC-32801378"></a>Issue Tracking</h2>
<div class="i1">
<p>
Many bugs reported end up not being a
bug in the log4net code,
@@ -215,7 +257,7 @@
<a
href="http://issues.apache.org/jira/browse/LOG4NET";>Search the bug database</a>
to see if the bug
you are seeing has already been
reported. If it has been reported then you can vote for the issue.
</p>
- <h3><a
id="HC-20092482"></a>Reporting an Issue</h3>
+ <h3><a
id="HC-26999600"></a>Reporting an Issue</h3>
<div class="i1">
<p>
If after you have exhausted all
other resources to resolve a problem you may want to file a bug report.
@@ -235,18 +277,121 @@
<li><b>Stack Traces</b> - Any
stack traces generated by the bug, if any.</li>
<li><b>Example</b> - Example
configuration files or web applications which demonstrate the bug. When
submitting an example which reproduces the bug, please try to make it as simple
as possible.</li>
<li><b>Bug Fix Patch</b> - A
patch created using <span class="code">diff -u</span> which fixes the bug. (If
you have found a bug fix which can be applied to the code).</li>
- <li><b>Description of the
Bug</b> - A description of the bug, include observed as well as expected
behaviour.</li>
+ <li><b>Description of the
Bug</b> - A description of the bug, include observed as well as expected
behavior.</li>
<li><b>Miscellaneous</b> - Any
other information you feel will help track down the problem.</li>
</ul>
<p>
<b>Just reporting a bug will
not fix it. A good bug report includes a detailed description of the
- problem and a succinct test
case which can reproduce the problem.</b>
+ problem and a succinct test
case which can reproduce the problem.</b> The very best sort of report
+ includes an NUnit testcase
which reproduces the issue, this means that we can fix it and that we can
+ be sure that it stays fixed in
future!
</p>
<p>
- <a
href="http://issues.apache.org/jira/browse/LOG4NET";>Report a log4net bug</a>.
+ <a
href="http://issues.apache.org/jira/browse/LOG4NET";>Report a log4net issue
here</a>. You will need to login to JIRA before you can submit an issue.
</p>
</div>
</div>
+ <h2><a
id="HC-25706868"></a>Contributing Patches</h2>
+ <div class="i1">
+ <p>
+ Before starting to work on a patch it
is probably a good idea to join the log4net-dev
+ mailing list to check that equivalent
or complementary work is not already underway.
+ </p>
+ <p>
+ Currently the only supported way of
submitting patches to log4net
+ is via the JIRA issue tracking system.
+ </p>
+ <p>
+ The preferred method of generating a
patch is a unified context diff against
+ the latest development version in CVS.
To do this you should do the following:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Get the latest version
of the code from CVS, see the section above on
+ <i>Anonymous CVS
Access</i> for details on how to obtain the CVS version.
+ </p>
+ </li>
+ <li>
+ <p>
+ Make your code changes
to the log4net source. Please follow existing
+ code styles where
possible. If adding new API methods or classes then
+ these should be
appropriately documented with code comments.
+ Contributions intended
for inclusion in ASF products must be licensed
+ to ASF under the terms
of the
+ <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache Software License</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ Generate a unified
context diff for the files you have changed. Run the
+ <span class="code">cvs
diff -u > patch-file</span> command from the root of the log4net
+ codebase to generate a
diff file.
+ </p>
+ </li>
+ <li>
+ <p>
+ If you have added new
files these will not be included in the diff. You
+ will need to attach
these files separately.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If you are not using CVS then you can
still generate a unified context diff
+ using the <i>diff</i> GNU tool. The GNU
tools are available for Windows as part
+ of the <a
href="www.cygwin.com">Cygwin</a> package.
+ </p>
+ <p>
+ If you are unable to generate a diff
please submit each file separately and place
+ block comments around each code change
to highlight the differences.
+ </p>
+ <p>
+ In order to submit your patch please
follow the following steps:
+ </p>
+ <ul>
+ <li>
+ <p>
+ Create a new issue for
your patch. On the
+ <a
href="http://issues.apache.org/jira/browse/LOG4NET";>log4net issues home page</a>
+ select the <i>Create
New Issue</i> from the menu bar. You will need to be logged
+ into JIRA in order to
create an issue.
+ </p>
+ </li>
+ <li>
+ <p>
+ Select the issue type
as appropriate.
+ </p>
+ </li>
+ <li>
+ <p>
+ Prefix the summary with
<b>[PATCH]</b>. Enter a description of the changes made,
+ new features, or bug
fixes in your patch.
+ </p>
+ </li>
+ <li>
+ <p>
+ Once the issue has been
created you can attach your patch file to the issue
+ by selecting the
<i>Attach file to this issue</i> operation from the left hand
+ menu. When attaching
your patch you must select the <b>Grant license to ASF for
+ inclusion in ASF
works</b> option. If attaching a patch please include in the
+ description the
baseline version of log4net you used to build your patch, if against
+ a CVS version please
include the date and branch (e.g. HEAD).
+ </p>
+ </li>
+ <li>
+ <p>
+ If you have other files
to attach, e.g. you have added new files to log4net, then
+ attach each file
separately. Please include in the description the name of the file
+ attached and the path
it should live in the project.
+ </p>
+ </li>
+ </ul>
+ <p>
+ A notification will be sent to the
log4net-dev list once you have created your issue,
+ however it may also be worth mailing
the log4net-dev list to encourage the project
+ committers to apply your patch, or at
least find out when they may do so.
+ </p>
+ </div>
</div>
