Definition of Ready
We assume that the issue has already been assigned to a developer who is then responsible for checking through the following conditions before making code changes.
1 2 3 4 5 6 7 8 9 10 | |
The markdown above should be copied into the issue description where the items are used as headings. The readiness checklist will be used by the product owner to confirm that the issue is ready for development.
Development environment is up-to-date
The developer must synchronise their development environment by pulling all the latest changes from GitHub. In this section of the readiness checklist, note down that the refresh has been done and any additional actions that you had to take.
All existing tests pass
Before making any changes to code, the developer should run all relevant unit tests. If there are any failures, these need to be investigated before starting work on the current issue. It may be that someone else's changes have caused the problem, but this needs to be established. Once the cause is know, a decision can be taken about how to handle it. For example, it could be passed back to another developer for resolution, or the fix could be incorporated into the current issue.
Development branch is created
This may be done in the IDE, but the new branch must be pushed to GitHub so that it is visible to others. In the readiness checklist, make a note of the name of the new branch.
Use cases are defined and documented
Use cases are a simple way to break the requirement down in terms of what the different actors need. The documentation is arranged like this:
└── documentation
├── erd.drawio
├── use_cases.drawio
└── use_cases
├── use_case_1.drawio
├── use_case_1_activity.drawio
├── use_case_2.drawio
├── use_case_2_activity.drawio
├── use_case_3.drawio
:
It is assumed that the diagrams are created using diagrams.net
hence the .drawio extension. The use case diagram at the top level is a summary; where
a use case needs breaking down further, a more detailed diagram is placed in the
use_cases directory. The name of the detailed diagram should be the same as the item
in the summary diagram - i.e. replace use_case_1 etc. with the actual name of the
use case.
When preparing for a task, the summary diagram should be updated, and a new detailed diagram should be added if needed. The new file versions will be checked in along with the modified code.
Leaf use cases should be expanded as one or more activity diagrams. The diagram file corresponding to an activity diagram appends _activity to the filename as shown above.
In the readiness checklist, list any new use cases in the form of a series of checkbox items, ticking them off as you deal with them. You can use the example below as a template for creating a checklist.
1 2 3 | |
Acceptance criteria are defined
Acceptance criteria are high-level goals that need to be demonstrated at the end of the development. They are probably closely related to the documented use cases. They should be documented as a series of checkbox items as described above and checked off after development to show that the criteria have been met.
Any database changes are identified and documented
Appropriate techniques should be applied in order to decide on what database changes are needed. The ER diagram for the application should be updated, and in addition, the changes should be listed in this section of the readiness checklist as a series of checkbox items. The items should be ticked off as you deal with them.
Any dependencies/impacts are identified and documented
Once a codebase becomes fairly complex, there may be many interconnections between the different pieces of code. A major risk when changing code is that you will alter something that another piece of code relies on. One way to resolve this problem is to make sure that code is properly tested, that code coverage is sufficiently high and that tests are run on a regular basis. However, that is to fix the problem after it has occurred. To avoid the problem in the first place requires some investigation in advance to identify code that might be affect by your change. This is sometimes known as impact analysis.
GitHub lets you search a codebase for occurrences of text strings. This forms the basis of an impact analysis but it is important to make sure that you are only searching the target repository. You can do this by appending repo: USERNAME/REPOSITORY to the search string. For example, if you are searching the repository MyApp, owned by user charlie, for occurrences of the string myvar, you should enter the following into the GitHub search box.
1 | |
GitHub search does not work well with certain characters including underscores. You need to replace underscores (and other special characters) with a dot as a single-character wildcard. If your search string contains whitespace, you also need to enclose it in double quotes. To search for from package_x import *, for example, you need to enter
1 | |
If you are a Mac or Linux user, you can have more control over your search if you use
grep on your local copy of the repo at the command line. Using grep, you need to
escape any special characters such as asterisks with a backslash. You need to use the
-r switch so that grep descends into subdirectories. You can also tell
grep to ignore case by using the -i switch, and to report only the name of the
matching file with the -l switch. See the examples below.
1 2 | |
1 2 | |
1 2 | |
When performing an impact analysis, search for
- The name any database object that you will be changing
- The name of any file you will be changing
- Any other item (e.g. program variable) if you intend to change its name
- Any tests related to the results from the above searches
In this section of the readiness checklist, you should document the searhes you have performed. You should list the files that need to be modified as a series of checkbox items. Under each of these, add a comment that specifies what additional steps need to be taken in completing your change. The checkboxes are ticked off as you complete the changes to the impacted files.
The issue has been elaborated
If the issue is complex, it will need splitting into a series of manageable tasks. Elaboration is the process of working through the requirement to establish the detail and to work out how to break it down. There will probably be some relationship between the list of the tasks and the use cases that have been identified. This is a good thing: the more consistency there is in the documentation, the easier it is to understand.
The series of tasks should be documented as checkbox items which are ticked off as you deal with them.
To accommodate any impacts that you have identified, you will probably need to change existing pieces of code that are not directly related to the issue you are working on. You may decide to combine those changes with yours as you go along, but it may be better to separate out any preparatory steps into their own tasks. For example, if you intend to rename a database attribute, it would be sensible to make the change in the existing code and re-run all existing tests before you go on to make any further changes related to your issue.
Each task listed against an issue should have a clear description. If there is any ambiguity or there are any gaps, the issue is not yet ready for development.
Tests have been identified and documented
The type of test and a rough testing strategy should be described for each task. A test description should specify the requirements of the test such as data fixtures or mocked elements.
Each test should be documented as a checkbox item which can be ticked off once the test is implemented and the test is successful.
Each task is feasible
There should be no experimental tasks included at this stage. If the proposed solution involves a novel treatment of some kind - i.e. something not done elsewhere in the application - a trial should be performed in advance and the results noted in the readiness checklist. This section does not contain any checkbox items; instead, it is a place for descriptive notes.