<?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>How to report an issue ?</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 reporting an
        issue to the Checkstyle project. We welcome anything: bug reports, feature requests
        to existing functionality, new Check ideas, etc.
      </p>

      <p>
        Our issue tracker system is at Github -
        <a href="https://github.com/checkstyle/checkstyle/issues">
        https://github.com/checkstyle/checkstyle/issues</a>.
      </p>
    </section>

    <section name="How to report a bug?">

      <p>
        First and foremost, do not think that your issue is obvious and do not need details.<br/>
        Even tiny issue need all details
        (Check name, config with options, source file, Checkstyle version) and context to be
        shared with us.
      </p>

      <p>
        The best way to report an Issue is to reproduce it by our
        <a href="cmdline.html#Download_and_Run">
        Command Line Interface (CLI)</a>. It is the most minimalistic way to launch Checkstyle.<br/>
        PLEASE use our latest released version.
      </p>

      <p>
        Our project is NOT responsible for problems at any extension or plugins.<br/>
        Checkstyle is library that is used by number of IDEs and static analysis services.<br/>
        We fix problems that are only reproducible on latest release.
      </p>

      <p>
        We need minimized but compilable Java file and minimized config with one Check
        that cause problem.<br/>
        We do not need real source code. Any obfuscation of your super secret code is OK.<br/>
        Link to your source code would be awesome.
        Code has to be compilable, in other case behaviour could be strange.
      </p>

      <p>
        Example of report that we expect (you can skip <code>-Duser.language=en
        -Duser.country=US</code> if your default locale is English):

        <source><![CDATA[
Check documentation: https://checkstyle.org/config_whitespace.html#WhitespaceAround

/var/tmp $ javac Test.java

/var/tmp $ cat Test.java
public class Test{ // Doesn't warn - incorrect
private static final int SOMETHING = 1;
}

/var/tmp $ cat config.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
        "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
  <module name="TreeWalker">
    <module name="WhitespaceAround">
      <property name="allowEmptyTypes" value="true"/>
    </module>
  </module>
</module>

/var/tmp $ java -Duser.language=en -Duser.country=US -jar checkstyle-6.XX-all.jar \
  -c config.xml Test.java
Starting audit...
Audit done.

        ]]></source>
      </p>

      <p>
        Always specify what is expected.<br/>

        <code>
          Expected: violation on first line.
          /var/tmp/Test.java:1:28: error: '{' is not preceded with whitespace.
        </code>
      </p>

    </section>

    <section name="How to request new feature for existing functionality?">

      <p>
        Please always specify exact name of the Check/Module.
      </p>

      <p>
        Please provide detailed description of problem and chunks of code and config
        that you currently have.
      </p>

      <p>
        Imagine that everything is possible and propose name of the new option and its behaviour.
        Do not think that your issue is so obvious.
      </p>
    </section>

    <section name="How to request new Check/Module?">
      <p>
        Please provide detailed description of problem.
      </p>
      <p>
        You have to provide examples of code and expected violations on them.
        The more examples the better.
      </p>
      <p>
        If you have open source project, please send a link to the whole java file.
      </p>
    </section>

  </body>
</document>
