Public | Automated Build

Last pushed: a year ago
Short Description
Harvest <-> Jira syncing.
Full Description

h1. BugYield

BugYield is a console application which tracks changes to tickets (issues, work items, bugs whatever) across systems (two-way) to avoid tedious double registrations.
Which means that the developers only need to track time in Harvest, and then ticket-titles will be transferred automatically from your ticket system to the Harvest time entry AND time spend on that ticket will be synchronized in the chosen ticket-system.

BugYield currently supports two ticket management systems "FogBugz": and "Jira": and time tracking system "Harvest":

Important note: We haven't been using FogBugz for years, and cannot confirm it still works.

h2. Installation

Clone the repository and remember to initialize submodules ("git submodule init" and "git submodule update"). Downloads are currently not functional as GitHub does not include submodules.
CURL and PHP 5.3 must be installed (5.2 won't cut it!).
You might need to change the #! path in the "bugyield" file. Use "which php" in order to find the proper path.

h2. Configuration

BugYield needs to know where and how to access the systems involved. This configuration is handled by a config.yml file. Copy the provided config.sample.yml and update it with account information. If your configuration file is not located in the root directory you can specify the path to the config file using the <code>--config</code> option.

h2. Usage

BugYield currently supports two use cases:

Time synchronization: Mapping entries in Harvest to time elapsed in FogBugz or Jira tickets

Title synchronization: Mapping ticket titles from FogBugz or Jira to Harvest entries

BugYield works in the context of one or more Harvest projects identified through their id, full name or code. Projects can be specified in the configuration or using the <code>--harvest-project</code> option.

Run <code>./bugyield</code> from the command line to show all available commands.

Time synchronization example:

<code>./bugyield tim --bugtracker=a-label</code> Run BugYield with the bugtracker defined in config.yml with the label "a-label"

Title synchronization example:

<code>./bugyield tit --bugtracker=a-label</code> Run BugYield with the bugtracker defined in config.yml with the label "a-label"

Just change the <code>--bugtracker=XXXX</code> with another label to run another bugtracker. We have current one FogBugz instance and two Jira bugtrackers configured in the same config.yml

h3. Running in docker

When running in docker, you should mount in the config file:

docker run -v /path/to/config.yml:/bug-yield/config.yml reload/bug-yield

In development, you can mount in the full source and run a command immediately:

docker run -v /path/to/config.yml:/bug-yield/config.yml reload/bug-yield /bug-yield/bugyield --bugtracker=sometracker tim

h3. Time synchronization

BugYield can update tickets in FogBugz and Jira with time registrations in Harvest. This makes it easier to show how much time has been spent on a ticket and how this corresponds with estimates.

It works like this:

Add <code>#[ticket-id]</code> without the []'s in the Harvest entry notes

Run the timesync command

The elapsed time field for the FogBugz/Jira ticket is updated and a new comment/worklog is added to the ticket showing the entry id, the time spent, the task type and the notes from Harvest.

If the time or task for the Harvest entry is changed at a later point in time, subsequent execution of the timesync command adds a new comment to the ticket and the elapsed time field is adjusted accordingly.

If a Harvest entry contains multiple ticket ids the time spent is distributed evenly across the mentioned tickets.

If BugYield detects serious inconsistencies, then it will email the offending user and optionally a separately defined email address (e.g. to the Project Manager).

h4. PRO TIP for JIRA

Make sure that the Closed state is editable in your Jira workflows, thus enabling bugyield to update worklogs on closed issues - see "Jira documentation":

h3. Title synchronization

BugYield can update entries in Harvest with ticket titles from FogBugz and Jira. This makes it easier register time on specific tickets without typing other than the ticket-number (prefixed with a <code>#</code>).
NOTE: When an entry has been submitted and thereby locked, then we can't edit the entry, and it will fail.

It works like this:

Add <code>#[ticket-id]</code> without the []'s in the Harvest entry notes

Run the titlesync command

The entry notes in Harvest are updated with the ticket titles from FogBugz/Jira replacing <code>#[ticket-id]</code> with <code>#ticket-id</code>

If a FogBugz/Jira ticket title is changed at a later point in time, subsequent execution of the titlesync command makes sure that the Harvest entry notes are updated accordingly.

h2. To do

  • Disable support for FogBugz - we don't use it anylonger and haven't testet it for a long while.

h2. Known errors and problems

h3. CURL and SSL errors

When synchronizing with FogBugz we sometimes get SSL certificate errors. A quick fix is to make CURL ignore invalid SSL certifikates. Do that by adding this line to vendor/fogbugz-php-library/src/fogbugz_request.php on line 32:
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,false); // added by rasmus, ignore SSL verification. @See
I'm sure that there are better ways of handling this issue...

h3. Brackets in ticket titles

If you put brackets in your ticket title, you make it difficult for BugYield to recognize our "codes". It will handle the ticket, but display warnings and remove any comments on the Harvest entry created by the user.

Docker Pull Command
Source Repository