To etablish the principle of Behaviour Driven Development in our development process we searched for a possibility to verify, if an acceptance criteria is fullfilled or not. Because we usually host our repositories at GitHub we decided to use the GitHub issue tracker to describe our features and acceptance criterias.

Setup

Issues

As a first step the following two additional labels have to be added to the projects issue tracker.

• feature
• bdd

Feature issues will then be created and marked with the feature label (See example here). For every acceptance criteria that belongs to an issue a separate issue labeled with bdd will be created (See example here). The BDD issues are described in the following manner:

GIVEN two numbers x and y
WHEN passing the numbers to the logarithmic function
THEN the function returns the logarithmus with base x of y

Milestones

We distinguish between two different milestone types:

• Version milestones
• Feature milestones

Version Milestones

For every planned release version a version milestone will be created, named with the version number (i.e. milestone for version 1.0.0 will be named 1.0.0). A version milestone groups all feature issues that belong to the corresponding release version. That means, that all feature issues have to be assigned to its appropriate version milestone.

Feature Milestones

For every feature a feature milestone will be created. Feature milestones are prefixed with the feature issue number they belong to (See example here). In the next step all bdd issues of the corresponding feature will be assigned to the feature milestone.

Contribute code

Test Code

The acceptance criterias described in the bdd issues of a feature will be implemented as unit tests. One or more unit tests could be implemented to ensure the fullfillment of an acceptance criteria. The unit tests have to be marked with the WorkItem annotation that refers to the issue bdd issue key:

[TestMethod]
[WorkItem(4)]
public void TestMethod()
{
    // Test code
}

The above code sample shows a unit test method that implements the acceptance criteria described in bdd issue #4. When committing test code the corresponding bdd issue key has to be referenced in the commit message (i.e. #4 or resolves #4).

Non Test Code

When committing non test code the issue key of the feature has to be referenced in the commit message.

Explanation

The described method allows to track all release versions and the completion state of the feature issues that belong to a release. The feature milestones encapsulate all associated bdd issues and will be completed as soon as all of its bdd issues (acceptance criterias) have been resolved. As soon as all feature issues have been resolved the version milestone will be completed.

If the commit messages always contains the key of the feature or bdd issue the corresponding issue automatically represents the change history. The annotation on the test methods help to resolve the acceptance criteria (bdd issue) directly from the source code.

At first glance it looks like an overhead added to the issue tracking but it’s a possibility to improve the quality of software development because it enables keeping track of the fullfillment of the defined accpetance criterias.

We created a GitHub repository that shows the described method (See links). For more details have a look into the Wiki.

Links

• Sample GitHub Repository
  • Wiki
  • Issue Tracking