<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.0//EN" "http://forrest.apache.org/dtd/howto-v10.dtd">
<howto>
  <header>
    <title>How to Contribute a Patch via Bugzilla</title>
    <abstract>
      Bugzilla is the Internet-based mechanism to facilitate contributions to
      any Apache project. This includes changes to code and documents (Patches),
      and also reports of flaws in the system (Bugs), and suggestions for
      enhancement. In this How-to we will concentrate on the Patch tracking
      capabilities of Bugzilla. We will explain how to create your Bugzilla
      account, how to enter a patch description, and finally how to attach the
      actual patch file.
    </abstract>
    <last-modified-content-date date="2002-05-25"/>
  </header>
  <audience title="Intended Audience">
    <p>
      This document is meant for first-time users of Bugzilla. The web interface
      can be daunting, so this concise explanation will help you to start. After
      your first patch submission, you can proceed to make more substantial
      contributions.
    </p>
    <p>
      As our example we use the contribution of a simple documentation patch for
      the Apache Cocoon project. The principles apply to any project.
    </p>
  </audience>
  <prerequisites title="Prerequisites">
    <p>
      Bugzilla contributors should:
    </p>
    <ul>
      <li>Understand what a Patch is and how to make one.
Note that a new complete document is still just a &quot;patch&quot;,
though it does need separate treatment to a normal &quot;diff&quot;.
</li>
      <li>Understand that Bugzilla is the Apache Bug Database. Bugzilla does not
distinguish between a Bug report, a Patch submission, and an Enhancement suggestion. They are all <em>&quot;Bugs&quot;</em> as far as Bugzilla is concerned.
</li>
    </ul>
  </prerequisites>
  <steps title="Steps">
    <p>
      Here is how to proceed. Go to
      <fork href="http://issues.apache.org/bugzilla/">Bugzilla</fork> in another
      browser window.
    </p>
    <section>
      <title>1. Create your Bugzilla Account</title>
      <p>
        Follow the link the home page to &quot;Open a new Bugzilla
        account&quot;. Do not worry, you will not be sent spam email nor
        bombarded with advertisements by setting up this account. It is purely a
        workgroup tool.
      </p>
      <p>
        Note that you can conduct queries in Bugzilla and review submissions
        without having an account. However, to make a contribution you must have
        an account. This ensures legitimacy. It also enables the system to send
        you email automatically when your patch is applied by a Cocoon
        committer.
      </p>
    </section>
    <section>
      <title>2. Enter a new bug report</title>
      <p>
        Follow the "Enter a new bug report" link from the Bugzilla home page.
        First, you will be asked to select the relevant project ... choose
        Cocoon 2 of course. Next, you will be asked to provide your account
        details. Following that, you will be presented an input form for the
        various details ...
      </p>
      <p>
        <img src="my-images/bugzilla-screen.gif" alt="Bugzilla Screen" height="342" width="479" />
      </p>
      <section>
        <title>Specify Version</title>
        <p>
          This is the version of Cocoon that you prepared your patch against.
          Choose <code>Current CVS</code> if you have an up-to-date local
          working copy of HEAD branch or a very recent nightly build. Otherwise
          choose the relevant release version. This is a very important step, as
          you will confuse the committer if your changes do not match the
          repository. If you are unsure, then please say so in the description
          at step 12.
        </p>
      </section>
      <section>
        <title>Specify Component</title>
        <p>
          Follow the &quot;Component&quot; link for description of the available
          components. If you do not know which component is relevant, then just
          use <code>core</code>.
        </p>
      </section>
      <section>
        <title>Specify Platform</title>
        <p>
          This is really meant for bug reporting. Perhaps it could be relevant
          for a patch. You would usually specify the <code>All</code> option.
        </p>
      </section>
      <section>
        <title>Specify Operating System (OS)</title>
        <p>
          Really meant for bug reporting. Perhaps it could be relevant for a
          patch. You would usually specify the <code>All</code> option.
        </p>
      </section>
      <section>
        <title>Specify Severity</title>
        <p>
          The impact that would arise if your patch is not applied. For a
          documentation patch, the severity would usually be the default
          <code>Normal</code>. However, if it addressed some serious lack or
          fixed a misguided configuration statement, then the impact could be
          <code>major</code>.
        </p>
        <p>
<!--FIXME: (DS) Why include this if it isn't recommended for a patch? -->
<!--       (DC) To try to discourage them from using it. Does it need
better words? -->
          (The <code>enhancement</code> option would not be used for a patch, as
          it is intended for suggesting something that should be done. Use this
          option wisely. It would be better to discuss it on the mailing list
          first.)
        </p>
      </section>
      <section>
        <title>Specify Initial State</title>
        <p>
          Use the <code>New</code> option.
        </p>
      </section>
      <section>
        <title>Specify Assigned To</title>
        <p>
          Leave it blank. Your patch will be automatically assigned to the
          <code>cocoon-dev</code> mailing list. When a committer takes on your
          patch, that committer will assign the bug to their own email address.
          This pevents duplication of effort by other committers.
        </p>
        <p>
          The Cc field can be used if you need the bug reports, and any
          follow-up, to be copied to some other person. Remember that your
          report will be sent automatically to the <code>cocoon-dev</code>
          mailing list, so you do not need to Cc anyone there.
        </p>
      </section>
      <section>
        <title>Specify URL</title>
        <p>
          If the patch refers to a particular document, then provide the website
          URL. If it refers to an issue with one of the local Cocoon Samples,
          then provide the localhost URL.
        </p>
      </section>
      <section>
        <title>Carefully choose the Summary</title>
        <p>
          The summary will become the all-important title of the bug. Use it
          wisely. You want to draw attention to your patch. Just as with posting
          email to the listervers, choosing a poor title may cause your posting
          to be easily overlooked. Use up all the characters available ... about
          60 maximum.
        </p>
        <p>
          Start the Summary with the <code>[PATCH]</code> tag. This will ensure
          that it is included in the Cocoon automated patch queue summary posted
          to the mailing lists. The patch queue summary reminds people what
          patches are pending. If you omit this tag, then your patch may easily
          be overlooked.
        </p>
      </section>
      <section>
        <title>Description</title>
        <p>
          Provide a brief explanation of what your patch does. Supply any
          instructions to help the committer apply your patch efficiently. Note
          any issues that may remain. It may help to list each file that you are
          submitting and briefly describe what it is. A committer will need to
          provide a descriptive log message when committing your work. Providing
          a clear description here will help them.
        </p>
        <p>
          Consider writing the Description and Summary text before you start
          entering your patch report. You could save it in a local text file
          beforehand and then copy-and-paste it when the time comes.
        </p>
        <p>
<!--FIXME (DS): Do we need this? It's a patch, not a bug. It may be confusing. -->
          If this were a bug report, then it would need extensive description.
        </p>
      </section>
    </section>
    <section>
      <title>3. Send the patch report</title>
      <p>
        Review your options, then press the <strong>Commit</strong> button. This
        will add an entry to the bug database and email a report to the
        <code>cocoon-dev</code> mailing list and a copy to you. Your submission
        will be assigned a unique Bug Number which you can use to review its
        progress.
      </p>
      <p>
        The next steps will show you how to attach your patch to the report that
        you have just created ...
      </p>
    </section>
    <section>
      <title>4. Create an attachment of the actual patch</title>
      <p>
        You will be presented with a status screen saying that your bug report
        was accepted and that email was sent to <code>cocoon-dev</code> mailing
        list.
      </p>
      <p>
        Now you have a choice ... proceed to review your bug report by selecting
        the link &quot;Back to Bug #XXXXX&quot;. If you forgot to mention
        something, then you can add more comments. From that screen, follow the
        link &quot;Create a new attachment&quot;. Otherwise follow the link from
        this status screen to &quot;Attach a file to this bug&quot;.
      </p>
      <section>
        <title>Specify the file to be uploaded</title>
        <p>
          Provide the local pathname to your patchfile, e.g.
          <code>/home/me/work/cocoon/patch/howto-bugzilla.tar.gz</code>
        </p>
      </section>
      <section>
        <title>Describe the attachment</title>
        <p>
          Provide a concise one line description, e.g. <code>Gzipped TAR archive
          with new docs and diffs</code>
        </p>
      </section>
      <section>
        <title>Specify the contentType of the attachment</title>
        <p>
          If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then
          select &quot;<code>Binary file
          (application/octet-stream)</code>&quot;. If it is just a single xml
          document, then select &quot;<code>Plain text
          (text/plain)</code>&quot;. If the patch is just a single diff file,
          then select &quot;<code>Patch file (text/plain, diffs)</code>&quot;.
        </p>
      </section>
    </section>
    <section>
      <title>5. Submit the attachment</title>
      <p>
        When you are ready, press the <strong>Submit</strong> button. As for
        Step 3, you will be presented with a status screen saying that your
        attachment was accepted and that email was sent to
        <code>cocoon-dev</code> mailing list.
      </p>
    </section>
    <section>
      <title>6. Be patient</title>
      <p>
        Now your patch will wait inside Bugzilla until one of the Cocoon
        committers assigns the patch to their own email address and starts to
        process it to apply it to the master CVS repository. As the registered
        owner of the Bug, you will be sent an automatic email at each of these
        stages.
      </p>
    </section>
    <section>
      <title>7. Add more description or attachments if necessary</title>
      <p>
        Until the patch is applied by the committer and the Bug report is
        closed, you can still add more to your bug report. However, only do this
        when absolutely necessary because the patch should not be changing while
        the committer is trying to commit it. If you just want to make further
        changes, then it would be better to wait until your patch is applied.
        Then you can make a new patch. Remember that the committer has full veto
        and may decide to make some slight modifications to your patch. So it is
        far better to wait.
      </p>
    </section>
    <section>
      <title>8. Adding subsequent patches to the same document or program</title>
      <p>
        If you want to make more patches to the same file, then please open a
        new Bug rather than re-open the old one. After all, once the original
        patch is applied by the committer, its corresponding Bug report is
        closed.
      </p>
    </section>
  </steps>
  <extension title="Real World Extension">
<!--FIXME: (DS) The purpose of this is to provide examples of how they can use
                  the knowledge gained in this how-to -->
    <p>
      Contributing patches, in the form of documentation or code, is a vital way
      to give back to the Cocoon community. For example, you might consider
      contributing a timely patch in the form of a new FAQ, how-to, or tutorial.
      Or, you may also consider submitting a patch which updates Cocoon's
      existing user and developer guides.
    </p>
  </extension>
  <tips title="Tips">
    <section>
      <title>Setting user preferences</title>
      <p>
        You can configure certain preferences, though the Bugzilla defaults work
        just fine.
      </p>
    </section>
    <section>
      <title>Review the bugzilla documentation</title>
      <p>
        There are various explanations of terminology and procedures ... follow
        the links should you need to know more.
      </p>
    </section>
    <section>
      <title>Search Bugzilla</title>
      <p>
        Bugzilla has a very powerful search interface. Now that you have a login
        account, Bugzilla can remember customized queries which you can run with
        a single click.
      </p>
    </section>
  </tips>
  <references title="References">
    <ul>
      <li>
Bugzilla is at 
<link href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</link></li>
      <li>
Helpful Bug Writing Guidelines are available directly from the
Bug entry interface.
</li>
    </ul>
  </references>
</howto>
