Definition of ready

This article provides a definition of ready to enable a development team to decide when a task is ready to be started with.

The target audience are developers contributing to one of my projects, be it open source or commercial. It can also be of interest for people who are looking for a basis for their own guidelines.

This document is distributed under the CC BY 4.0 license.

Scope

These guidelines only apply to issues once they enter the state "ready". During earlier states ("new", "backlog") issues only need a descriptive title. Everything else can be empty and added as more details emerge.

General

• The issue has at least one label to describe its context.
• The issue is assigned to a milestone.
• The issue is assigned to a project.
• The state of the issue is "ready"

Feature issues

TODO: Guidelines for title

• Optional: In the description a section "Dependencies" list everything that is needed before the implementation can start. For example:
  • References to issues that need to be completed first
  • Fixes or enhancements of external libraries
  • External rules or laws to come into effect
  • Answers from external contacts to critical questions
• The description has a section "Story" describing a user story.
  • The user story uses the template:

    As (role) I want (feature) so that I can (have value).

  • Exceptions: Pure improvement or cleanup issues can omit the user story.
• The description has a section "Goals" (acceptance criteria).
  • Together, all goals describe what is needed for the issue to be done.
  • Each goal describes a state that can be tested. TODO: Link to guidelines for requirements.
  • Goals that cannot be validated by an end user or tester are marked as "Internal:". For example:

    Internal: All TODO#123 comments are resolved.

• Optional: At the end of the "Goals" section the estimated effort is noted. For example:

  Estimation: 10h

  Rationale: This can be used by Siisurit to compare it with the actual effort from time tracking.

• Optional: The description has a section "References" that points to resources needed to implement it. For example:
  • Links to API documentation
  • Process diagrams
  • Attachments with required external documentation
• Optional: The description has a sections "Example" that point to or show example input data or expected output data. These can be helpful to describe the scope or provide early test data.

Bug issues

When a feature issue went into production and turned out not to work as expected, create a bug issue.

• The issue title indicates what needs to be fixed. Examples:
  • pygount#33 Fix count of string only lines
• The issue is labeled as bug.
• The issue description matches the following template:

  1. Steps to reproduce
     • If the bug cannot be reproduced yet, mention this here.
  2. Actual result
  3. Expected result

• Optional: A reference to the original issue that should have implemented the desired functionality.
  • If there is no such issue and requirement, consider treating the issue as feature that might be billed. This can be particularly true for special cases not described in the original issue because the customer forgot to mention them during the requirement analysis.
• Optional: The issue references data that might aid in the analysis. For example:
  • Screenshots or videos
  • Log files
  • Stack traces
  • Links to support issues
  • Quotes from emails

Pull requests

When a pull request is ready to be reviewed:

• The title references the original issue starting with the issue number.

  Example: pygount#107 #106 Clean up source analysis from file

• The text refers to the original issue, either as:

  • "Close #123": After merging the pull request on GitHub or GitLab, this automatically closes the original issue.
  • "See #123": Even after merging the pull request the original issue remains open

• The pull request has no labels.

  Rationale: Relevant labels are already set at the original issue. Setting the same labels here would be redundant and error-prone.

• Important In GitHub, leave the "Development" field empty for now and only after merging the pull request also link it to the original issue. Otherwise, the issue would automatically be closed upon merge. This is a misfeature of GitHub that cannot be disabled.