Building "Definition of Done" and "Acceptance Criteria" lists in JIRA

In Agile Methodologies, most specifically Scrum, Definition of Done (DoD) and Acceptance Criteria lists are very important concepts. They bind what the Product Owner wants to what the Development Team will deliver. In fact, it can be seen as a contract between two parties.

Putting them on paper is simple. The difficulty often lies into having the Development Team actually respecting the contracts; even when the team is well intentioned. Teams with a dedicated Scrum Masters may not have any issues with respecting the DoD as the Scrum Master will push them to ensure that every User Story’s Acceptance Criteria are met and that it respects the DoD. Unfortunately, the reality is that a lot of teams don’t have a dedicated Scrum Master and that the Scrum Master’s role is just another hat that a member has to wear.

So what can a team do to ensure that the DoD and Acceptance Criteria are respected? From our experience, the most effective way is to try to embed them in their natural workflow. Since the development team is using JIRA and probably JIRA Agile, embed the DoD and Acceptance Criteria list directly in JIRA!

This article will expose good DoD and Acceptance Criteria management tips and practices and how to apply them inside JIRA.

Creating the DoD

The DoD usually contains elements applicable to different phases of the development. In our DoD, we have elements applicable to Technical Tasks (sub-tasks), User Stories (Issues), Sprints and even Releases. The Checklist Add-on can help you for the Technical Tasks and User Stories elements.

First, install Checklist and create a new custom field of type Checklist for the DoD related to Technical Tasks:

  • From the Custom Fields admin page, click on the “+ Add Custom Field” button
  • In the “Step 1 of 2” screen:
    • Select the Checklist custom field type.
    • Click on the “Next >>” button.
  • In the “Step 2 of 2” screen:
    • Enter “Definition of Done” for the Field’s Name.
    • Enter “Definition of Done for Technical Tasks” for the Field’s Description.
    • For the applicable issue types, select “Technical task” or/and any issue types that are usually used as sub-tasks.
    • For the applicable context, either leave it as is or select the projects for which you want the DoD applied.
    • Click on the “Finish” button.
  • You should now be presented with a page asking you to associate the new custom field to JIRA screens. Associate the field with the “Default Screen” so that the DoD appears on the create and edit views. You can also associate the field to the “Resolve Issue Screen” so that the development team can mark the DoD items as done when they resolve the issue. This will also come in handy if you decide to enforce the DoD later on. When finished, click on the “Update” button.

Now, create another custom field of type Checklist for the DoD related to User Stories:

  • Follows the same steps as mentioned for the Technical Tasks’ DoD but this time, in Step 2:
    • Enter “Definition of Done for User Stories” for the Fields’ Description.
    • Select “Story” for issue type. If your team also uses other issue types that are treated the same way as User Stories, you can select them as well. In fact, you can select any issue type that shares the same DoD as the User Story.

Configuring the DoD items

Now that our DoDs are created, they need to be configured if we want them to be of any use. The thing to remember with a DoD is that it should be applicable to any issue but we surely don’t want to manually recreate the DoD every time a new issue is created. Since Checklist is a multi-select custom field, it is possible to use Options to configure its items.

From the Custom Field page, find the DoD applicable to Technical Tasks and from its Action Menu (Cog icon), select “Configure”. This will bring you to the custom field configuration page. From there, click on the “Edit Options” link. In the Options page, enter all the DoD items that are applicable for Technical Tasks. Typical items are:

  • Code compiles and is entered in CM
  • Code builds without warnings
  • Code unit tested - All green
  • Peer Reviewed

You enter a DoD Item by adding a field Option Value. Options can then be sorted alphabetically or in any order you deem important. Once options are entered in the custom field, they become available to any new or previously created issue. This means that you can open and edit any Technical Tasks that is not yet closed and you will see the Technical Task DoD appear. Even better, if you add other items to the DoD later on and re-edit the same Technical Task, they will be displayed as well. This is a powerful feature for managing a DoD over time. We will cover this in the next section.

Now, you can repeat the same steps to create the User Story DoD items. Typical items for a User Story can be:

  • All Acceptance Criteria met
  • Documentation updated
  • Build published to demo server

By having a DoD for the different issue types, we can customize the criteria based on the workflow. When the User Story will be created, it will have its own particular DoD Items. When the story will be split into Technical Tasks during the Sprint Planning, each technical task will have DoD Items related to the software development practice.

Managing the DoD

A DoD is a live document that should be reviewed regularly. As practices become engrained into the day-to-day activities, you may want to replace some DoD items with other less engrained practices. For example, when the team naturally creates unit tests for all their classes, you may want to move to Test Driven Development (TDD). Therefore, you would want to the replace the DoD Item “Code unit tested - All green” with “Code developed using TDD”.

Although you can delete/rename items and replace them with new ones, a much better practice is to disable the items. When editing DoD Items via the Option page, every entered option has a “Disable” hyperlink. Disabling an option will keep the option in the system but will prevent it from appearing in the issue. So, when creating a new issue, the disabled DoD items will not appear in the issue. By disabling items instead of deleting them, you keep a record of your DoD evolving through time. You can then see which practices are now natural for the team and on which ones they are still struggling.

Since the DoD is a contract between the Product Owner and the Team, it is natural to want to fit as many items in the DoD as possible in order to ensure the quality of the product. As good as it sounds in theory, in practice, having too many DoD items can backfire on you. When some teams are confronted with too many DoD items, they either work on a subset or them or worst, they do a very bad job trying to do them all and eventually stop looking at the DoD all together.

So, the safer approach is to be reasonable with the number of items listed in the DoD. Pick the ones that are really important and on which the team should focus. When they become good at it, replace the items with new ones. As the adage says: “Rome wasn’t built in a day”. But what if you want to challenge your team a little bit? Simple, make some DoD items mandatory and some optional. Fail the sprint if one or many DoD Mandatory Items have been skipped but let it be a success when only optional items were skipped. Make it clear that the optional items will someday become mandatory! This will challenge the team in taking on more while still having the impression of being in control.

Checklist offers you the capability of setting items optional. From the custom field configuration page, select the “Edit Discretionary Options” hyperlink. You will be presented with the list of active options entered for the field. Simply select the DoD Items that you wish to make optional. When you make DoD Items optional, it is good to let the developers know which items are mandatory and which ones are optional. Go back to the custom field configuration page and select the “Edit Parameters” link. When in the parameters page, select the “Emphasize Mandatory Items” option and make sure that it is checked. The mandatory and optional DoD Items should now be displayed differently.

Enforcing the DoD

Like we mentioned in the introduction, the best way to have a team follow the DoD is to embed it into their workflow. Checklist comes bundled with a workflow validator that can be used to enforce the DoD. This validator will prevent the Technical Task or User Story to be resolved or closed until all the DoD Items have been completed. So, when a user tries to resolve the issue that he is working on, the validator will verify if all the DoD Items have been checked. If it is not the case, JIRA will prevent the issue workflow transition. The developer will then be reminded that some of the DoD items still have to be implemented.

To add the Checklist validator to your workflow, edit your project’s workflow and:

  • Select the transition onto which you want to attach the Checklist validator. This is usually the “Resolve Issue” transition or the “Close Issue” transition or both.
  • From the transition page, click on the “Validators” hyperlink and then on the “Add” hyperlink.
  • From the “Add Validator” page, select the “Checklist Validator” and click on the “Add” button.
  • Select the checklist custom field, in our case, the “Definition of Done” field. Since we have two custom fields with the same name, it might be difficult to determine which one you are selecting. They are usually displayed in the same order as the one listed in the Custom Fields page. It might also be a good idea to have subtly different names.
  • Now, decide the validation type you want. You can either enforce that all items are checked or simply the mandatory ones. If you have optional items in your DoD, you should chose to validate only the mandatory one.
  • Don’t forget to publish the workflow changes if you want them to take effect.

Et voila, you have now enforced your DoD and made sure that the development team is aware of it. Be careful, if you simply attach a validator to the “Resolve Issue” transition, it is possible to uncheck DoD Items after the issue has been resolved. So, a better practice is to put the validator on both the Resolve and Close transitions or at the very least on the Close one.

Acceptance Criteria list

While a DoD is global for all issues of a certain type, the Acceptance Criteria list is specific for every User Story. Checklist is perfect for Acceptance Criteria lists as it allows adding Items directly at the issue level.

Follow the procedure described previously to create a DoD but this time, create a custom field named “Acceptance Criteria” and assign it to the “Story” issue type. Since it doesn’t really make sense to have global acceptance criteria, there is no need to create options for the field. However, if it is required, Checklist supports both mode simultaneously, i.e. global and local items.

Now, when a new user story is created, the Product Owner can add acceptance criteria directly from the issue creation page so that they become immediately available to the developer. The developers then just need to check them off when they meet them. Just like the DoD, a workflow validator can be added to the Acceptance Criteria list in order to enforce it when the story is resolved or closed.

Managing who can add Acceptance Criteria

It might be a good practice to limit who can add/change/remove Acceptance Criteria. In theory, the Product Owner is responsible for specifying the criteria so it only makes sense that he be the only one managing them.

Access the custom field configuration page for the Acceptance Criteria field and click on the “Edit Parameters” link. In the parameter page, select the role which should have the rights to manage the list. By default, the “Administrators”, “Developers” and “Users” role are listed in the “Edit Roles” section. While we can limit the access to the administrators, it makes a lot more sense to create a new role called “Product Owners”. Once the new role has been created, it should be available in the “Edit Roles” section. By selecting the “Product Owners” role, only the users having that role will be able to edit the Acceptance Criteria. Users are added to the “Product Owners” role by the project administrator.

In Conclusion

Managing Definition of Done (DoD) and Acceptance Citeria lists directly in JIRA is not overly complicated and can lead to teams finally acting on them.

Add new comment