src/xdocs/contributing.xml - platform/external/checkstyle - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>

 <document xmlns="http://maven.apache.org/XDOC/2.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

   <head>
     <title>Contributing</title>
     <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/>
     <script type="text/javascript" src="js/anchors.js"/>
     <script type="text/javascript" src="js/google-analytics.js"/>
     <link rel="icon" href="images/favicon.png" type="image/x-icon" />
     <link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
   </head>

   <body>
     <section name="Content">
       <macro name="toc">
         <param name="fromDepth" value="1"/>
         <param name="toDepth" value="1"/>
       </macro>
     </section>

     <section name="Introduction">

       <p>
         Hey, good to see you on this page. It means that you are
         considering a contribution of your own work to the Checkstyle
         project. We welcome anything: bugfixes, new check modules, unit
         tests, documentation improvements, build process simplification,
         etc.
       </p>

       <p>
         This document assumes you are working with the GIT version of
         checkstyle and that you are familiar with some standard
         development tools (

         <a href="https://git-scm.com">GIT</a>,
         <a href="http://maven.apache.org">Maven</a>,
         <a href="http://junit.org">JUnit</a>).
       </p>
       <p>
         To start the development - visit our
         <a href="beginning_development.html">Beginning Development</a> page.
       </p>
       <p>
         <b>ATTENTION:</b> if you have idea how to improve Checkstyle please create issue on
         our <a href="https://github.com/checkstyle/checkstyle/issues">tracking system</a>.
         As soon as one of admins of our project approved your idea you are good to start
         implementation and you will be welcome with final code contribution.
         Please do not expect that we will accept any code that you send to us.
         Example of ideal <a href="https://github.com/checkstyle/checkstyle/issues/258">issue description</a>,
         and how it is commented on fix <a href="https://github.com/checkstyle/checkstyle/pull/601">Pull Request</a>.
       </p>
     </section>

     <section name="Report an issue">

       <p>
         All functional changes in project should have registered issue and wide explanation in it.
         Issue number has to be referenced in git commit message, see format below.
       </p>

       <p>
         To report issue please follow our best practices page - <a href="report_issue.html">
           How to report an issue ?</a> (<a href="report_issue.html#How_to_report_a_bug">How to report a bug ?</a>)
       </p>
     </section>

     <section name="Quality matters">

       <p>
         The developer team of checkstyle is really a lazy bunch of
         people.  We try to avoid work as best as we can, but most of all
         we try to avoid working on bugs that are reported by end users.
       </p>

       <p>
         To that end, we use a set of development tools that ensure that
         the quality of our code is kept at a fairly high level. Like
         most projects today, we use JUnit to test our code. However we
         do take this one step further and measure the coverage of our
         unit tests using

         <a href="http://cobertura.github.io/cobertura/">Cobertura</a>.

         This means it is not sufficient to pass all tests, but the tests
         should ideally execute each line in the code, code coverage should be 100%. To generate the
         Cobertura report, run the Maven command

         <code>mvn cobertura:cobertura</code>.

         Check results on report target/site/cobertura/index.html in project home folder.
       </p>

       <p>
         Besides using unit testing, we obviously also use checkstyle to
         check it's own code.
       </p>

       <p>
         The Maven command <code>mvn clean verify</code> must pass
         without any errors.
       </p>

       <p>
         If you add new end user features (Check, Filter, ....), remember to document
         them in JavaDoc of java classes and xdoc files that used to generate that site.
         Please recheck site and all bundles generation by <code>mvn clean site</code>
       </p>

       <p>
         The last step of verification that all works fine please do testing of your
         functionality on any open-source project (Spring, Hibernate, ....).
         Here is how to do it from <a href="http://checkstyle.sourceforge.net/cmdline.html">command line</a>
       </p>
     </section>

     <section name="Submitting your contribution">

       <p>
         Once you have made sure that your changes pass the Maven command
         <code>mvn clean verify</code>, the code coverage is of high
         standard and everything is documented, then you are ready to
         submit your work.
       </p>

       <p>
         Please use <a href="https://help.github.com/articles/using-pull-requests/">Pull Request</a>
         feature of <a href="https://github.com/">Github</a>.<br/>
         Please provide wide description of update with detailed explanation of problem
         and how you propose to resolve it.
         <b>ATTENTION:</b> Please recheck that in your Pull Request there is ONLY your changes and all of them are rebased from most recent HEAD of our master branch.
       </p>

       <p>
         <b>ATTENTION:</b> Please provide single-line meaningful message for commit with reference to github issue or Pull Request for more details.<br/>
         Ideal format for message is "Issue #Number: Brief single-line message ..... .". Where NUMBER is Issue or Pull Request number at github.
         <a href="https://github.com/checkstyle/checkstyle/commit/9303fd9d971eb55cdfd62686ba2f5698edb2c83e">Good example</a>
       </p>

       <p>
         After you do Pull Request please recheck that where are no problems from our build systems:
         <a href="https://travis-ci.org/checkstyle/checkstyle">Travis</a> and others ... .
         You will see that your Pull Request on Github is marked by that jobs automatically in few minutes.
       </p>

       <p>
         We are not only lazy but at times we are also busy with our day
         jobs.  This means that you might not always get an immediate
         answer. You are not being ignored, and we value your work - we
         might just be too busy to review your code, especially if it is
         a bit complex. If you don't get a response within two weeks,
         feel free to send a reminder email about your tracker item.
       </p>
     </section>
   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>

	<document xmlns="http://maven.apache.org/XDOC/2.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

	<head>
	<title>Contributing</title>
	<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/>
	<script type="text/javascript" src="js/anchors.js"/>
	<script type="text/javascript" src="js/google-analytics.js"/>
	<link rel="icon" href="images/favicon.png" type="image/x-icon" />
	<link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
	</head>

	<body>
	<section name="Content">
	<macro name="toc">
	<param name="fromDepth" value="1"/>
	<param name="toDepth" value="1"/>
	</macro>
	</section>

	<section name="Introduction">

	<p>
	Hey, good to see you on this page. It means that you are
	considering a contribution of your own work to the Checkstyle
	project. We welcome anything: bugfixes, new check modules, unit
	tests, documentation improvements, build process simplification,
	etc.
	</p>

	<p>
	This document assumes you are working with the GIT version of
	checkstyle and that you are familiar with some standard
	development tools (

	<a href="https://git-scm.com">GIT</a>,
	<a href="http://maven.apache.org">Maven</a>,
	<a href="http://junit.org">JUnit</a>).
	</p>
	<p>
	To start the development - visit our
	<a href="beginning_development.html">Beginning Development</a> page.
	</p>
	<p>
	<b>ATTENTION:</b> if you have idea how to improve Checkstyle please create issue on
	our <a href="https://github.com/checkstyle/checkstyle/issues">tracking system</a>.
	As soon as one of admins of our project approved your idea you are good to start
	implementation and you will be welcome with final code contribution.
	Please do not expect that we will accept any code that you send to us.
	Example of ideal <a href="https://github.com/checkstyle/checkstyle/issues/258">issue description</a>,
	and how it is commented on fix <a href="https://github.com/checkstyle/checkstyle/pull/601">Pull Request</a>.
	</p>
	</section>

	<section name="Report an issue">

	<p>
	All functional changes in project should have registered issue and wide explanation in it.
	Issue number has to be referenced in git commit message, see format below.
	</p>

	<p>
	To report issue please follow our best practices page - <a href="report_issue.html">
	How to report an issue ?</a> (<a href="report_issue.html#How_to_report_a_bug">How to report a bug ?</a>)
	</p>
	</section>

	<section name="Quality matters">

	<p>
	The developer team of checkstyle is really a lazy bunch of
	people. We try to avoid work as best as we can, but most of all
	we try to avoid working on bugs that are reported by end users.
	</p>

	<p>
	To that end, we use a set of development tools that ensure that
	the quality of our code is kept at a fairly high level. Like
	most projects today, we use JUnit to test our code. However we
	do take this one step further and measure the coverage of our
	unit tests using

	<a href="http://cobertura.github.io/cobertura/">Cobertura</a>.

	This means it is not sufficient to pass all tests, but the tests
	should ideally execute each line in the code, code coverage should be 100%. To generate the
	Cobertura report, run the Maven command

	<code>mvn cobertura:cobertura</code>.

	Check results on report target/site/cobertura/index.html in project home folder.
	</p>

	<p>
	Besides using unit testing, we obviously also use checkstyle to
	check it's own code.
	</p>

	<p>
	The Maven command <code>mvn clean verify</code> must pass
	without any errors.
	</p>

	<p>
	If you add new end user features (Check, Filter, ....), remember to document
	them in JavaDoc of java classes and xdoc files that used to generate that site.
	Please recheck site and all bundles generation by <code>mvn clean site</code>
	</p>

	<p>
	The last step of verification that all works fine please do testing of your
	functionality on any open-source project (Spring, Hibernate, ....).
	Here is how to do it from <a href="http://checkstyle.sourceforge.net/cmdline.html">command line</a>
	</p>
	</section>

	<section name="Submitting your contribution">

	<p>
	Once you have made sure that your changes pass the Maven command
	<code>mvn clean verify</code>, the code coverage is of high
	standard and everything is documented, then you are ready to
	submit your work.
	</p>

	<p>
	Please use <a href="https://help.github.com/articles/using-pull-requests/">Pull Request</a>
	feature of <a href="https://github.com/">Github</a>.<br/>
	Please provide wide description of update with detailed explanation of problem
	and how you propose to resolve it.
	<b>ATTENTION:</b> Please recheck that in your Pull Request there is ONLY your changes and all of them are rebased from most recent HEAD of our master branch.
	</p>

	<p>
	<b>ATTENTION:</b> Please provide single-line meaningful message for commit with reference to github issue or Pull Request for more details.<br/>
	Ideal format for message is "Issue #Number: Brief single-line message ..... .". Where NUMBER is Issue or Pull Request number at github.
	<a href="https://github.com/checkstyle/checkstyle/commit/9303fd9d971eb55cdfd62686ba2f5698edb2c83e">Good example</a>
	</p>

	<p>
	After you do Pull Request please recheck that where are no problems from our build systems:
	<a href="https://travis-ci.org/checkstyle/checkstyle">Travis</a> and others ... .
	You will see that your Pull Request on Github is marked by that jobs automatically in few minutes.
	</p>

	<p>
	We are not only lazy but at times we are also busy with our day
	jobs. This means that you might not always get an immediate
	answer. You are not being ignored, and we value your work - we
	might just be too busy to review your code, especially if it is
	a bit complex. If you don't get a response within two weeks,
	feel free to send a reminder email about your tracker item.
	</p>
	</section>
	</body>
	</document>