README for the Zope JTracker Product

  This product is an issue tracker for Zope.

  **Tested Platforms**

    This version of the JTracker has been written on and for 
    Zope 2.6.0 and up. I have run the JTracker successfully
    on...

      - Zope 2.6.x
      - Zope 2.7.x


  **If you use virtual hosting**

    If virtual hosting is used the auto-generated (or manually
    filled in) path to the MailHost can be incorrect. If you see
    errors adding or following up to issues where the traceback shows
    references to "unrestrictedTraverse" at the end the "mailhost"
    property is set incorrectly. If you do know the true physical path
    to the MailHost you want to use and it differs from the value 
    shown then correct it. If you do not know the path you can also
    just fill in the ID of your MailHost object without any leading
    slashes and the first object with that ID that can be acquired 
    by the JTracker will be used.


  **Please use the BTreeFolder2 Product**

    Since version 1.3 of the JTracker it is recommended that you 
    install BTreeFolder2. To download BTreeFolder2, see
    http://hathaway.freezope.org/Software/BTreeFolder2 .

    BTreeFolder2 is a BTree-based Folder that is much more
    efficient than standard Zope folders and is able to scale to
    a much higher number of contained items.

    Once the BTreeFolder2 product is installed it is recognized
    by the JTracker package and it will be used for all subsequent
    newly instantiated JTracker objects. Existing JTracker instances
    can be upgraded with the help of a script that comes with this
    package. In order to upgrade, follow these steps:

      - Log into the Zope Management Interface (ZMI) and go to the
        folder where your JTracker(s) are located.

      - From the "Add" dropdown select "External Method".

      - Fill in the following fields:

        - Id: Any ID that is not yet taken

        - Title: (optional) title

        - Module Name: JTracker.updater

        - Function Name: BTreeConverter

      - Hit the "Add" button to instantiate the External Method

      - Click on your new external method in the ZMI

      - Click on the "Test" tab in the External Method to update.

    Depending on the number of JTrackers in the folder and the 
    number of issues in each this update may take a while. Once
    it is done you will see a small log of the changes that were
    applied.

    In some cases the upgrade process actually requires restarting
    your Zope server. A symptom that signals the need to restart is
    the appearance of error messages when clicking through the 
    JTracker and some of the issues.


  **Upgrading existing JTrackers**
    
    JTrackers now come with an updater script that can be invoked as
    an External Method. To update an existing JTracker instance 
    follow the following steps:

      - Log into the Zope Management Interface (ZMI) and go to the
        folder where your JTracker(s) are located.

      - From the "Add" dropdown select "External Method".

      - Fill in the following fields:

        - Id: Any ID that is not yet taken

        - Title: (optional) title

        - Module Name: JTracker.updater

        - Function Name: update

      - Hit the "Add" button to instantiate the External Method

      - Click on your new external method in the ZMI

      - Click on the "Test" tab in the External Method to update.

    Depending on the number of JTrackers in the folder and the 
    number of issues in each this update may take a while. Once
    it is done you will see a small log of the changes that were
    applied.

    In some cases the upgrade process actually requires restarting
    your Zope server. A symptom that signals the need to restart is
    the appearance of error messages when clicking through the 
    JTracker and some of the issues.


  **Talking to the JTracker via Email**

    The JTracker allows you to perform certain tasks via email. This 
    requires cooperation from several components, namely a dedicated
    email address (must be the same as the address set as 
    "jtracker_emailaddress" in the JTracker properties) and a mail 
    server that allows you to pipe mail for the dedicated email address 
    into a script instead of delivering it to a mail spool. The script
    gets the raw email text and issues a POST request to a method
    on the JTracker.

    One important consideration that must be kept in mind is that if
    someone talks to the JTracker via email it is not possible to determine
    what user they really are. Email addresses can be spoofed easily. 
    For that reason the email interaction is limited to the following:

      - creating new issues

      - commenting on existing issues

    This is basically what everyone with the permission "Submit JTracker
    Issues" can do. All other administrative requests must go through the 
    normal web interface.

    This is what you need to do to set it up:

      - Edit the configuration parameters in the "emailAccepter.py" script.
        This script is in the Extensions directory of the JTracker package.
        It allows you to specify the full URL where your JTracker resides,
        the email address that it receives mail under (this is just for 
        verification purposes to make sure only legitimate mail is piped
        into Zope), and an optional login and password in case your JTracker
        is not reachable for anonymous users or you have not enabled the
        "Submit JTracker issues" permission for Anonymous in the JTracker
        "Security" ZMI view.

      - Make your mail server invoke the "emailAccepter.py" script. How this
        is done varies from one mail server software package to another. I
        have set it up with Postfix (easiest) and Sendmail (a little more
        complicated). I used the /etc/aliases file to specify the email
        handling, like so::

          # JTracker email account is jtracker
          jtracker: "|python2.x /path/to/JTracker/Extensions/emailAccepter.py"

        You must ensure that the emailAccepter script can be found/read by the
        user account your mail server runs under (you may copy the script
        anywhere, there are no dependencies with the JTracker package itself)
        and that your mail server can execute the python binary. This is the
        added snag with sendmail, it wants all "approved" binaries to be
        in (or linked into) a specific folder (/etc/smrsh on RedHat).

        The script invocation can be done using other methods as well, such 
        as procmail.

        If you used the /etc/aliases route do not forget to run "newaliases"
        when you are done. At this point you should be OK, if not your email
        will bounce back. It is hard to debug the real reason for bouncing
        emails to the JTracker, I suggest you read up on your mail server
        package to get debugging help.

    Once you are set up on the receiving end here are the rules for sending
    email to the JTracker:

      - Email that does not have a issue ID ("issue_23") in the subject line
        but one of the items defined as "components" in the JTracker 
        properties will create a new issue. The subject line should also
        contain one of the request types defined under "request_types" in
        the JTrackeer properties. The full subject will end up being the
        issue title.

        Parsing for component and request type is case-insensitive. It must
        be spelled correctly, though. Faulty email will be discarded silently
        and will not lead to malformed issues being created.

        A subject line that will create a "Bug Report"-type issue for
        component "Widget" could look like this::

          widget bug report: I cannot log in anymore

      - Email that has a issue ID in the subject line is assumed to be a 
        comment on the issue. Since issue followups do not use titles the
        rest of the subject is not important and it will be discarded. An
        example subject line can be as simple as this::

          issue_123

        For convenience purposes it is possible to take the email sent out
        by the JTracker about a new issue or an issue followup and simply
        hit "Reply" and adding your comment in the body. This will do
        "the right thing" and create an issue followup. To improve readability
        you should make sure to trim unnecessarily quoted text from your
        reply.



