<?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="https://junit.org/junit5/">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.3F">
        How to report a bug?</a>)
      </p>
    </section>

    <section name="Build">
      <p>
        Project is following general maven layout and phases for build.
        Generated jars will be in folder <code>target</code>.
      </p>

      <p>
        Generate maven standard jar: <code>mvn install</code>
        <br/>
        Generate maven standard jar and skip all validations/verifications:
        <code>mvn -P no-validations install</code>
        <br/>
        Generate uber jar (checkstyle-all-X.XX.jar) to use our
        <a href="/cmdline.html">command line</a>:
        <code>mvn -P assembly package</code>
      </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="https://www.eclemma.org/jacoco/">JaCoCo</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
        JaCoCo report, run the Maven command:
        <br/>
        <code>mvn test jacoco:restore-instrumented-classes jacoco:report@default-report</code>.
        <br/>
        Check results on report target/site/jacoco/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 by
        <a href=
          "https://github.com/checkstyle/contribution/tree/master/checkstyle-tester#checkstyle-tester">
        our testing tool</a>. Generated report is required to be shared in Pull Request.
      </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 create a
        <a href="https://help.github.com/articles/using-pull-requests/">Pull Request</a>
        for your contribution. In the Pull Request description, add any explanations of the
        implementation nuances. Please read the Pull Request template for more requirements.
        <b>ATTENTION:</b> Please verify that the Pull Request contains ONLY your intended changes
        and is based on the most recent HEAD of our master branch.
      </p>

      <p>
        <b>ATTENTION:</b>The commit message must adhere to a certain format.
         It should be "Issue #Number: Brief single-line message", where NUMBER is the issue number
         at Github
         (see
         <a href="https://github.com/checkstyle/checkstyle/commit/9303fd9d971eb55cdfd62686ba2f5698edb2c83e">
         an example</a>).
         Small changes of configuration files, documentation fixes, etc. can be contributed by
         starting the commit message with one of "minor:", "config:", "infra:", "doc:",
         "dependency:" or "spelling:", followed by a space and a brief single-line message.
      </p>

      <p>
        After submitting a Pull Request, it will be automatically checked by
        <a href="https://travis-ci.org/checkstyle/checkstyle">Travis</a> and other continuous
        integration (CI) services.
        Therefore, please recheck after some minutes that the CIs didn't
        find any issues with your changes. If there are issues, please fix them by amending
        commit (not by separate commit) and provide an updated version of the same Pull Request.
      </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>

    <section name="Bounty">

      <p>
        Some (mostly important) issues are marked with the label
        <a href="https://github.com/checkstyle/checkstyle/labels/has%20bounty">has bounty</a>.
        By solving such problem, you will not only help the community,
        but also get free beer (in monetary terms to your paypal account).
      </p>

      <p>
        All you need to do is link your <a href="https://github.com/">github</a>
        account and <a href="https://paypal.com/">paypal</a> account through
        the <a href="https://www.bountysource.com/">bountysource</a> website.
      </p>
    </section>
  </body>
</document>
