<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
<document>
  <header>
    <title>Information for FOP Developers</title>
  </header>
  <body>
    <section id="intro">
      <title>Introduction</title>
      <p>These pages contain information that should be helpful for those developing FOP.
This certainly includes programmers, but may also include those contributing to the project in other ways.</p>
      <p>For basic and user information on FOP, please visit the <link href="http://xml.apache.org/fop">FOP homepage</link>.</p>
    </section>
    <section id="lines">
      <title>Development Lines</title>
      <p>There are currently three lines of development on the FOP product:</p>
      <ul>
        <li>The oldest is the one that releases are currently generated from, and is also called the "maintenance branch". Because of limitations in its design, the FOP committers decided to freeze new development on this branch, and are providing only bug fixes. This branch is tagged as "fop-0_20_2-maintain" in the CVS repository.</li>
        <li>The main development line is the future of FOP. It was spawned from the "maintenance" branch, but had to quickly be "broken" so that the needed redesign could be dropped into place. It is currently not as mature as the "maintenance" branch, but has far greater long-term prospects. It is also known as the "root" or "trunk" or "redesign".</li>
        <li>The "Alt Design" is exactly that: an alternative design approach. Because its efforts are largely complementary and parallel to the main development branch, and because it is expected to be merged at some point into the trunk, it is <link href="http://xml.apache.org/fop/design/alt.design/index.html">documented separately</link>. The authors of this effort are currently in the process of merging their work into the trunk.</li>
      </ul>
      <p>Please note that patches for enhancements to the maintenance branch will generally not be considered. Bug fixes are welcome there, but new developers are strongly encouraged to apply their efforts to the trunk development line.</p>
      <p>Because there is a fair amount of common information between the maintenance and trunk development lines, we attempt to document them together, highlighting differences only where needed.</p>
    </section>
    <section id="involved">
      <title>Getting Involved</title>
      <section id="apache-roles">
        <title>Understand Apache Roles</title>
        <p>Review the <link href="http://xml.apache.org/roles.html">Apache Project Roles and Responsibilities</link> document for an understanding of the various roles of contributors within the community.</p>
      </section>
      <section id="fop-tasks">
        <title>Understand FOP Development Tasks</title>
        <p>There are many different ways that you can help with FOP development. The following is a non-exhaustive list of ways that <em>non-programmers</em> can help. Remember that an hour spent on the tasks below is an hour that a programmer can devote to fixing bugs or adding features instead:</p>
        <ul>
          <li>Answer questions on the fop-user mailing list.</li>
          <li>Contribute examples that are useful to other users.</li>
          <li>Contribute test cases.</li>
          <li>Submit well-written feature requests.</li>
          <li>Submit well-written bug reports.</li>
          <li>Review open issues to see if you have any insight into them that might help a programmer solve the problem faster. Add comments and test cases as appropriate.</li>
          <li>Test newly-closed issues to make sure they are truly closed.</li>
          <li>Submit patches to the documentation.</li>
        </ul>
        <p>Of course, we're glad to have programmers help as well. Here are some additional tasks that would require programming ability:</p>
        <ul>
          <li>Fixing bugs.</li>
          <li>Implementing new features.</li>
        </ul>
      </section>
      <section id="fop-standards">
        <title>Understand FOP-related standards</title>
        <p>At the moment FOP is mainly a tool to render XSL-FO files to pdf. Therefore if you want to contribute to FOP you should become familiar with these standards. You can find links at <link href="../resources.html#specs">Specifications</link>.</p>
      </section>
      <section id="doc">
        <title>Review the Developer Documentation</title>
      </section>
      <section id="design">
        <title>Understand FOP's Design</title>
        <p>The design for FOP is specified under the <link href="http://xml.apache.org/fop/design/index.html">Design</link> section. This is where the information on how FOP is developed and designed
internally will be kept.
    </p>
      </section>
      <section id="mail-fop-dev">
        <title>Subscribe to the fop-dev Mailing List</title>
        <p>Use this forum to discuss topics related to FOP development, including patch submissions, bug reports, and design issues. Please <em>do not</em> use it for XML support, XSLT support, XSL-FO support, or even FOP support.
Appropriate mailing lists for these topics can be found on the <link href="../maillist.html">FOP Mailing List</link> page.
        </p>
        <ul>
          <li>
To review the archives, you have several options:
            <ul>
              <li>The <link href="http://marc.theaimsgroup.com/?l=fop-dev&amp;r=1&amp;w=2">Mailing list ARChives</link> (MARC) at the AIMS group (search).
              </li>
              <li>
The <link href="http://nagoya.apache.org/eyebrowse/SummarizeList?listName=fop-dev@xml.apache.org">Apache Eyebrowse</link> archive (search, list by date, author, subject, or thread).
              </li>
              <li>
The <link href="http://xml.apache.org/mail/fop-dev/">Apache Mailing List archive</link>.
              </li>
            </ul>
          </li>
          <li>Before posting questions to any list, see "<link href="../maillist.html#general">General Information</link>".</li>
          <li>
See <link href="http://xml.apache.org/mail.html#fop-dev_fop-cvs">Apache XML Mailing Lists</link>
for detailed subscription information.
          </li>
          <li>
To subscribe (digest only): Send email to <link href="mailto:fop-dev-digest-subscribe@xml.apache.org">fop-dev-digest-subscribe@xml.apache.org</link>.
          </li>
          <li>
To subscribe fully: Send email to <link href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</link>.
          </li>
          <li>
For standard help: Send email to <link href="mailto:fop-dev-help@xml.apache.org">fop-dev-help@xml.apache.org</link>.
          </li>
          <li>
To unsubscribe: Send email to <link href="mailto:fop-dev-unsubscribe@xml.apache.org">fop-dev-unsubscribe@xml.apache.org</link>.
          </li>
        </ul>
      </section>
      <section id="mail-fop-cvs">
        <title>Subscribe to the fop-cvs Mailing List</title>
        <p>When changes are committed to the code repository, a record of the diffs is emailed to the fop-cvs mailing list. FOP developers are encouraged to subscribe to this list because it helps in following the progress of the project.
        </p>
        <ul>
          <li>Review the archives at <link href="http://marc.theaimsgroup.com/?l=fop-cvs&amp;r=1&amp;w=2">Mailing list ARChives</link> (MARC) at the AIMS group (search).</li>
          <li>Subscribe by sending an email to <link href="mailto:fop-cvs-subscribe@xml.apache.org">fop-cvs-subscribe@xml.apache.org</link>.</li>
        </ul>
      </section>
      <section id="dev-code">
        <title>Download and Use the Developers' Code Using CVS</title>
        <p>Between releases the newest code can be accessed via cvs. To do this you need to install a cvs
     client on your computer, if it is not already there. An explanation how to connect to the
     FOP source repository can be found at <link href="http://xml.apache.org/cvs.html">http://xml.apache.org/cvs.html</link>.
     An introduction into cvs and the cvs manual can be found in the
     <link href="http://xml.apache.org/library.html">reference library</link>.</p>
      </section>
      <section id="patches">
        <title>Submitting Patches</title>
        <p>If you have useful changes to source code (bugfixes or enhancements), test files, or documentation that you would like to contribute to the project, please do the following:</p>
        <ul>
          <li>If your changes include source code, make sure that it does not break FOP (i.e. make sure that FOP still compiles with your changes).</li>
          <li>If your changes include test files, review the <link href="testing.html">Testing page</link>.</li>
          <li><link href="tools.html#cvs_patch">Create a patch file</link> for the differences to be applied to the existing code.</li>
          <li><link href="../bugs.html#issues_new">Create a new bugzilla issue</link> for the patch. Include the text "[PATCH]" at the beginning of the description. Attach the patch file to the issue.</li>
        </ul>
        <p>One of the committers will test your patch and consider its implications for the project. They will then either commit it to the repository or explain on the issue why they did not. Depending on the work load and skill-sets of the various committers, it may take some time before a a submitted patch is addressed.</p>
      </section>
    </section>
  </body>
</document>
