Creating and Modifying Issues

OK, now you have an issue database, you can add issues to it. This is done using the add command. You’re prompted for the issue name, type, and a possibly multi-line description. You can also add comments.

There are three different types of issue in PyDitz:

Feature:A new feature you want to add to your project, which typically is visible to its users. Task:A thing that needs doing, but doesn’t necessarily add new functionality for users. Bugfix:Something broken that needs mending.

Here’s an example:

Ditz: add
Title: Implement a hello-world program
Description (ctrl-c to abort, . to finish)
> Pretty lame, but one has to start somewhere.
> .
Is this a (b)ugfix, (f)eature or (t)ask? f
Issue creator (enter for "Dilbert <dilbert@cubicle.com>"): 
Comments (ctrl-c to abort, . to finish)
> I already have a prototype for this, off the Interweb.
> .
Added issue helloworld-1

As you can see from the final line, each issue is assigned a name of the form <name>-<num>, where <name> is the name of the component assigned to the issue, and <num> is the next number available for that component. If issue names are mentioned in comments and descriptions, they’re treated specially—more on that later.

Note that if the issue database had any releases defined, we’d be asked if we wanted to assign it to one of them. More on that in Assigning Issues to Releases.

On creation, each issue database has one component: the name of the project. For simple projects, you might want to stick with this. But for more complex projects, it’s a good idea to group issues by component.

Here’s how to add a component, say, for issues related to programs:

Ditz: add-component
Name: prog
Added component prog

Let’s suppose we need another for the documentation:

Ditz: add-component
Name: doc
Added component doc

Now you have multiple components, you can assign issues to them:

Ditz: set-component helloworld-1
Changing the component of issue helloworld-1: Implement a hello-world program
  1) prog     2) doc    
Choose a component (1--2): 1
Comments (ctrl-c to abort, . to finish)
> This is a programming issue.
> .
Issue helloworld-1 is now prog-1.  Other issue names may have changed.

Note that, in the command loop, PyDitz remembers the last issue created or referred to by commands. So the helloworld-1 argument could have been omitted here.

You can also abbreviate issue names, by typing just enough of the component to make it unique, followed by the issue number. So if no other component starts with h, you could use h1 to refer to the issue above. If you only use the default single component, you can leave it out completely and just use the number. If there’s any ambiguity, PyDitz will say so and list all the possible issues that match what you typed.

New in version 0.10: Abbreviation of issue names.

You’ll also notice that PyDitz reports a change in the issue name—as you’d expect, since the name is partly determined by its component. This might also affect the names of other issues. But note that references to issue names in comments and descriptions are not affected—again, more on that later.

Issues can also have references—that is, links to other files not included in the issue database. Here’s an example (omitting the issue name here, since we’re referring to the last and only one):

Ditz: add-reference
Adding a reference to prog-1: Implement a hello-world program
Reference: http://warez.com/hello-world-trojan.c
Comments (ctrl-c to abort, . to finish)
> Prototype for the program.
> .
Added reference to prog-1

To pad out the example a bit more, let’s add a couple more issues:

Ditz: add
Title: Write some documentation
Description (ctrl-c to abort, . to finish)
> Sigh.  I suppose it's gotta be done.
> .
Is this a (b)ugfix, (f)eature or (t)ask? t
  1) helloworld     2) prog           3) doc          
Choose a component (1--3): 3
Issue creator (enter for "Dilbert <dilbert@cubicle.com>"): 
Comments (ctrl-c to abort, . to finish)
> .
Added issue doc-1

Notice here that, now we have more than one component, we’re asked which one to assign the issue to.

Now, for completeness, let’s add a bug report:

Ditz: add
Title: Prototype prints the Wrong Thing
Description (ctrl-c to abort, . to finish)
> It writes "goodbye cruel world".  Hmm, looks like a memory
> corruption to me.
> .
Is this a (b)ugfix, (f)eature or (t)ask? b
  1) helloworld     2) prog           3) doc          
Choose a component (1--3): 2
Issue creator (enter for "Dilbert <dilbert@cubicle.com>"): wally@cubicle.com
Comments (ctrl-c to abort, . to finish)
> .
Added issue prog-2