Building “Definition of Done” and “Acceptance Criteria” lists in JIRA
- Yves
Use Case
- +/- 7 minutes read
In Agile methodologies, specifically Scrum, Definition of Done (DoD) and Acceptance Criteria (AC) lists are very important concepts. They connect what the product owner wants to what the development team delivers. In that sense, they can be seen as contracts between the two parties.
Putting these lists on paper is simple. The difficulty often lies in getting the development team to actually uphold these contracts, even though they may have the best of intentions. Teams with a dedicated scrum master may not have any issues with this, as the scrum master will push them to follow both the DoD and AC. Unfortunately, the reality is that many teams don’t have a dedicated scrum master, and the scrum master role is just one of many hats that a member has to wear.
So what can a team do to ensure that the DoD and AC are followed? In our experience, embedding them into the team’s natural workflow can be highly effective. Since the development team is already using Jira Core and probably Jira Software, building the DoD and AC directly into Jira makes a lot of sense!
This article will outline good DoD and AC management tips and practices, as well as how to use Checklist to implement them.
This article will outline good DoD and AC management tips and practices, as well as how to use Checklist to implement them.
Creating a DoD
The DoD usually contains items that apply to the various phases of development. In the DoD we use here at Okapya, we have items for technical tasks (sub-tasks), user stories (issues), sprints, and even releases. The Checklist app can help you with the technical tasks and user stories parts.
By having separate DoDs for technical tasks and user stories, you can customize the checklist items to each of their unique workflows. When a user story is created, it will have its own particular DoD items. When the story is split into technical tasks during the sprint planning, each of those tasks will have their own development-related DoD items.
Creating technical tasks DoD
Once you have Checklist installed, the first step is to create a new Checklist custom field that you will use to build the technical tasks DoD.
For detailed instructions on how to do this, see adding a Checklist custom field. As you are working through the steps on that page:
- Name the new custom field “Definition of Done”, and give it the description “Definition of Done for Technical Tasks”
- Associate the custom field with the Default Screen so that the DoD appears when creating and editing an issue
- Associate the custom field with the Resolve Issue Screen so that the development team can mark the DoD items as done when the issue is resolved. This will also come in handy if you decide to enforce the DoD later
Creating a user stories DoD
Now, create another Checklist custom field for the user stories DoD. Follow the same steps as for the technical tasks DoD, but this time:
- Enter “Definition of Done for User Stories” as the field description.
Configuring the DoDs
On the Custom fields page, in the row for the technical tasks DoD, click the cog button in the Actions column and click Configure. This will bring you to the custom field configuration page.
Editing the configuration scheme context for the technical tasks DoD
First, click the Edit Configuration link to edit the configuration scheme context. For detailed information about this page, see Editing the configuration scheme context.
On this page, choose the issue types and projects to associate with the DoD:
- Under Choose applicable issue types, select Technical Task (or any other issue types that are used as sub-tasks).
- Under Choose applicable context, select the projects that the DoD should apply to.
Editing the global items for the technical tasks DoD
The thing to remember with a DoD is that while we want it to apply to any issue, we definitely don’t want to manually recreate it every time a new issue is created. To avoid that, you want to create global items.
Once you create global items for a custom field, they will be added to any new or existing issues. This means if you edit any technical task that is not yet closed, you will see the technical task DoD appear. What’s more, if you add other items to the DoD later on and edit the same technical task again, you will see those items too. This is a powerful feature for managing a DoD over time, which we’ll look at in more detail in a bit.
Click the Edit Global Items link to edit the global checklist items. For detailed information about this page, see Editing global items.
- Code compiles and is entered in CM
- Code builds without warnings
- Code unit tested — all green
- Peer reviewed
Editing the configuration scheme context for the user stories DoD
Since we now need to edit the other DoD, return to the Custom fields page. In the row for the user stories DoD, click the cog button in the Actions column and click Configure. Then, click the Edit Configuration link and follow the same steps as for the technical tasks DoD, but this time:
For detailed instructions on how to do this, see adding a Checklist custom field. As you are working through the steps on that page:
- When configuring the configuration scheme context, select Story as the issue type (or any other issue types that are used as issues).
Creating a user stories DoD
Click the Edit Global Items link, and like you did for the technical tasks DoD, enter all the items that apply to user stories.
Click the Edit Global Items link, and like you did for the technical tasks DoD, enter all the items that apply to user stories.
- All acceptance criteria met
- Documentation updated
- Build published to demo server
Managing the DoD
A DoD is a live document that should be reviewed regularly. As these practices become ingrained into your day-to-day activities, you may want to replace some DoD items with other less-familiar practices. For example, when the team naturally creates unit tests for all their classes, you may want to move to Test Driven Development (TDD). In that case, you could replace the DoD Item “Code unit tested — all green” with “Code developed using TDD”.
Don’t delete, disable
Although you can delete or rename DoD items and replace them with new ones, disabling them is a much better practice. When you were editing your DoD items on the Edit Global Items page, you probably noticed that each item had a toggle button in the Enable column.
Turning this toggle button off disables the global item, which means that its existing values will remain in the system, but the item will not appear in any new issues. Disabling items instead of deleting them keeps a record of how your DoD has evolved over time. You can then see which practices have become natural for the team and which ones they are still struggling with.
Less is more
Since the DoD is a contract between the product owner and development team, it’s natural to want to squeeze as many items into the DoD as possible to ensure that your product is top-quality. As tempting as this may be, having too many DoD items can backfire on you.
When some teams are confronted with too many DoD items, they either work on only a few or worse, they end up doing them all poorly and eventually stop looking at the DoD altogether. The safer approach is to only add a reasonable number of items to the DoD and stick to the really important ones you want the team to focus on.
Keep things interesting
Once the team gets comfortable with the items in the DoD, you can start replacing the items with new ones. As they say, Rome wasn’t built in a day. If you want to challenge your team a little, make some DoD items mandatory and some optional. Fail the sprint if mandatory items are skipped, and make it succeed when only optional items are skipped. Make it clear that the optional items will someday become mandatory! This will challenge the team to take on more while still giving them a sense of control.
To make sure Checklist is configured to allow mandatory items, make sure the Mandatory Items setting is turned on. For more details, see Editing parameters.
To learn how to make items optional, see Making mandatory items optional.
Enforcing the DoD
As we mentioned, 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 prevent a technical task or user story from being resolved or closed until all the DoD items have been completed.
If a developer tries to resolve the issue that they are working on, the validator will check whether all the DoD items are checked. If not, the workflow transition will simply not occur, reminding the developer that some of the DoD items aren’t done yet.
For detailed instructions on how to create a validator, see Setting up a Checklist Workflow Validator.
Although you can delete or rename DoD items and replace them with new ones, disabling them is a much better practice. When you were editing your DoD items on the Edit Global Items page, you probably noticed that each item had a toggle button in the Enable column.
While you are working through the steps:
- You can either enforce that all items be checked or only the mandatory items. If you have optional items in your DoD, you should only validate the mandatory ones.
- Attach the validator to either the Resolve Issue or Close Issue transition, or both.
If you attach a validator to only the Resolve Issue transition, DoD items can be unchecked after the issue is resolved. To avoid this, put the validator on both the Resolve Issue and Close Issue transitions, or at the very least, on the Close Issue one.
Voilà! You have now enforced your DoD and made sure that the development team is aware of it.
Creating an AC
While a DoD applies to all issues of a certain type, an AC list is specific to each user story. Checklist is perfect for creating acceptance criteria lists, as it allows you to add items directly at the issue level.
Follow the same procedure that you used to create the DoD, but this time:
- Name the new custom field “Acceptance Criteria” and assign it to the Story issue type.
- Skip creating global items, since it doesn’t really make sense to have global acceptance criteria (but if you need them, it’s still possible to create them).
Now, whenever a new user story is created, the product owner can add acceptance criteria directly from the issue creation page. They will immediately become available to the developers, who just need to check them off as they implement them. Just like the DoD, a workflow validator can be added to the AC list if you want to enforce it when the user story is resolved or closed.
Managing who can add acceptance criteria
It can be a good practice to limit who can add, change, or remove acceptance criteria. In theory, since the product owner is responsible for creating the criteria, it would make sense that only they should be able to manage them.
On the Custom fields page, click Edit Parameters. For a detailed description of this page, see Editing parameters.
In the Access Control tab, you’ll see the Edit Roles parameter, which has a drop-down list that specifies which roles have permission to manage the AC custom field. Although we could restrict access to the Administrators role, it would make more sense to create a new role called “Product Owners”. Once you have done so, select the Product Owners role to ensure that only users who are added to that role by the project administrator can edit the acceptance criteria.
In Conclusion
Managing Definition of Done (DoD) and Acceptance Criteria (AC) lists directly in Jira isn’t as difficult as you might think, and can encourage teams to finally act on them.
You might also like…
Creating a meeting in Google Calendar from Jira
Using Checklist for Jira with ScriptRunner Behaviors
