Team TogMine; A Guide To Setting Up Development Sandbox For TogMine

This is a quick-start guide for developers joining Team TogMine. It outlines and references all the links and documentation you need to get started developing TogMine. This documentation is necessary because TogMine is not a website, but a data pulling-processing-and-pushing tool, and preparing for development is different to most projects.

Rule number one

Do not forget your togs. Most folk know that they must never forget their pants. However Team TogMine not only need their pants. They need a special type of pants: Togs. Who would have thought? Do not forget your togs.

See also

These links are first because they are important. Go read them first. Count yourself lucky there is only one link.

• TogMine's public project page

Version 2 and upgrade path

There are many differences in the way version 2 works from version 1.

Most of these revolve around the fact that Redmine API module version uses Redmine's REST API instead of a database connection (as in version 1). And the abstraction of various new and old features common to both Toggl.com and Redmine API modules into REST API Query and User Access Keys modules, in order to promote code re-use.

All of TogMine's dependencies have been rewritten from the ground up. TogMine has been updated accordingly, but the port is not complete. There are also new unfinished features for TogMine in the works.

For existing Drupal user accounts, an upgrade path to retrieve API keys for each user with a Redmine user IDs has been implemented and works, but not yet thoroughly tested. This upgrade path requires both Redmine database access as well as REST API access, even though Redmine API module v2 only uses the REST API (after the upgrade).

The modules' dependency trees have changed significantly and a suggested upgrade path probably consists of something like;

1. drush cli
2. dis toggl redmine
3. en togmine
4. updb

Software Components

There are three software systems that make up TogMine and it's dependencies;

• Drupal 6, including the TogMine module and it's dependencies
• Redmine 1.1; The open source rails app.
• Toggl.com; A web service. No installation required.

Dependencies

TogMine v2's dependencies are;

• Redmine API v2
• Toggl.com API v2
• REST API Query
• User Access Keys

TogMine v1's dependencies are;

• Redmine API v1
• Toggl.com API v1

Commits

TogMine and it's dependencies are contributed modules on Drupal.org. But usually these modules will usually be tracked in a repository for the Drupal website you are installing/running TogMine on, such as the company's Drupal intranet. However commits to TogMine and it's dependencies should be pushed to Drupal.org, as well as the internal repository.

To achieve this easily you might like to replace sites/default/modules/togmine in your sandbox with a git-clone of togmine module from git.drupal.org. If you do this, you can cd to modules/togmine/ in order to commit changes to drupal.org, then cd .. to sites/default/modules/ to commit the same changes (or a group of them) to the company's repository.

You can do this for each of modules/togmine/, modules/toggl/, modules/redmine/, modules/rest_api_query/ and modules/user_access_keys/. Bevan (this author) highly recommends it.

Nested git clones do not interfere with each other because the "parent" git repository (the company's one) is already tracking the files in the "child" git repositories (Drupal.org). Adding new modules in this fashion does not work, but only because Git wants to be smart about handling the "child" repository as a git sub-module or something.

Issue tracking

Issues should be primarily tracked in the respective issue queue:

• TogMine
• Redmine API
• Toggl.com API
• REST API Query API
• User Access Keys API

Branches

The current development & stable branches are (at time of writing), respectively;

• TogMine, Redmine API, Toggl.com API: 6.x-2.x & 6.x-1.x
• REST API Query, User Access Keys: 6.x-1.x (no stable branch)

Development sandboxes

This guide helps you to setup a TogMine development sandbox on vash. Team TogMine developers may need or prefer a local sandbox too, especially for heavier lifting and more thorough testing, such as with SimpleTest.

To start with, set up a Drupal 6 sandbox (such as your company's intranet).

Before we can test TogMine, we need to connect TogMine to Redmine and Toggl:

Set the appropriate $conf variables in settings.php, as per the following examples:

/**
 * Redmine API module settings.
 *
 * Redmine API module v1 requires a database connection to Redmine.  Version 2
 * only requires the database connection for the upgrade path from version 1.
 *
 * The database scheme has to be the same for all databases;  Both "mysql" and
 * "mysqli" database schemes may not be used simultaneously in the same Drupal
 * instance.
 *
 * Redmine API module v2 requires $conf['redmine_access_point'].
 */

// Required for Redmine API module version 1 (and version 2's upgrade path).
$db_url = array(
  'default' => $db_url,
  'redmine' => 'mysqli://user:pass@localhost/redmine_sandbox',
);

// Required by Redmine API module version 2.
$conf['redmine_access_point'] = 'http://sandmine.example.com';

// Some features require a general-use global API key for Redmine:
//  - Up and coming features of TogMine v2.
//  - Redmine API module v2's SimpleTest unit tests.
// Use your own, admin or an admin user's API key.  You can steal other people's
// API keys from the "tokens" table in redmine.
$conf['redmine_api_key'] = '';



/**
 * Toggl.com API module settings.
 */

// Toggl.com API module v2's SimpleTest unit tests require this.
$conf['toggl_api_key'] = '';



/**
 * TogMine module settings.
 */

// Enable debug output when synchronizing with TogMine.
$conf['togmine_debug'] = TRUE;

// Work-around Redmine's missing REST API for activities.
// Defaults to 8 in togmine.module.
$conf['togmine_redmine_default_activity'] = 9;

// Do not filter by workspace.  This is important if you are using a Toggl.com
// sandbox user that is not in the company's Toggl.com workspace.
// $conf['togmine_toggl_workspace_id'] = FALSE;

// Override TogMine's synchronization period: 20 weeks.
// Defaults to 2 weeks in togmine.module.
// $conf['togmine_backlog_period'] = 20 * 7 * 24 * 60 * 60;

// Synchronize data back to a specified date: 1 April 2011
// $conf['togmine_backlog_period'] = time() - strtotime('2011-04-01');

Redmine

Redmine API module v2 connects to Redmine via a REST API and needs to know what the access point (base URI) is.
Version 1 connects to a Redmine MySQL database. Version 2 also connects to the database, but only for the upgrade path.

Do not connect TogMine sandbox environments to the production Redmine website or database.

If you are running a local development environment you can get Redmine running locally quite easily using webrick. You will need Rails and a MySQL server, but not Apache. This is highly recommended. Use brew to install the dependencies on a Mac. $conf['redmine_access_point'] will most likely be 'http://localhost:3000' in this case.

Toggl.com

Set $conf['toggl_api_token'].

If you are writing data to Toggl.com, create a "sandbox" user account on Toggl.com. Toggl.com API module v2's SimpleTest unit tests and some in-the-works features for TogMine write to Toggl.com.

Toggl.com does not provide a sandbox environment, so just create another dummy-user account and use that. Because the sandbox user's account will not be connected to your company's Toggl.com "Workspace", you will need to set $conf['togmine_toggl_workspace_id'] to FALSE (or to the sandbox user's workspace ID) for many features to work correctly, including TogMine synchronization.