Artemis Specification for Developers

This specification is a request for comments and proposals.

Contents

• General Info
  • Use Cases
  • Issue Format and Identity
  • Distributing Issues
• User Interace
  • List of Commands
  • Adding Issues and Comments
  • Issue Lists and Reports
  • Saving Reports
  • Standard Issue Fields
  • Commiting an Issue
  • Viewing a Issue
• Technical Details
  • Storage Organization
  • Performance

Use Cases

TODO: Explain the scope of Artemis, describe various distributed issue management use cases.

Issue Format and Identity

TODO: Describe an issue format.

Naming

An issue must have a global ID. Email messages already have such and ID -- the Message-ID field. In order to make IDs shorter we may use, for example, the first 12 characters of the Message-ID SHA-1 hash:

>>> hashlib.sha1(m['message-id']).hexdigest()[:12]
'13a1f49c4357'

Local IDs similar to local Mercurial changeset numbers are also needed in order to type less characters while running local commands. One may use the creation date of an issues as a key for ordering the local IDs.

2:fcdf8a97e633: Task 2 that was created later than Task 1
1:13a1f49c4357: Task 1 is the earliest one

Distributing Issues

TODO: Explain the ways of distribing issues (import, export, synchronization media, etc.).

List of Commands

• ilist — show a list or a table of issues
• iview — show an issue
• iadd — add a new issue or comment
• iaccept — accept an issue (?)
• iedit — edit an existing issue or a comment
• iremove — remove and issue or a comment

Adding Issues and Comments

TODO

Issue Lists and Reports

TODO

Saving Reports

TODO

Standard Issue Fields

In a particular project, one may want to limit himself to some standard issue fields and their values. These fields can be specified in the config file of Artemis, let us call it .artemisrc.

An example of issue fields specs in .artemisrc:

[fields]
state = new,accepted,reviewing,resolved
resolution = ,fixed,wontfix,duplicate,worksforme
component = ,documentation,code
priority = critical,major,minor

[defaults]
priority = major

[state]
new = new
open = accepted,reviewing
closed = resolved

It means that a new task looks like this:

From: John Smith <john.smith@example.com>
Date: Sun, 29 Nov 2009 20:28:19 +0300
State: new
Priority: major
Subject: brief description

Detailed description.

The fields resolution and component were not added, as they may contain an empty value.

Enumeration of values of the fields in the fields section specifies the ordering of values.

If one will try to specify an incorrect value while editing an issue (e. g. State: foo, then the issue is rejected as being not conforming to the specs.

Commiting an Issue

TODO

Viewing a Issue

TODO

Storage Organization

TODO

Performance

TODO: Provide an analysis of algorithmical complexity for main operations on issues (lising, searching, accessing, adding, etc.).