You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4net-dev@logging.apache.org by ni...@apache.org on 2005/04/25 01:51:22 UTC
cvs commit: logging-log4net/doc contributing.html
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>