Skip to end of metadata
Go to start of metadata

Table of contents

A. Context 

Requests are received from various programs, departments and entities within AMPATH for the development of specific software implementations. This document proposes to standardize the content and structure of these requests. This way, developers will be able to implement the details of a ticket with great details possibly with minimal additional engagement with the program/entity making the request. 

The proposed advantages are that this will ensure that:

  1. Ensuring the program representatives making the requests deeply consider all the various aspects required for the successful and satisfactory implementation of their requests 
  2. Ensuring that the software developers works productively with minimal back and forth engagement (once development has began) and where minimal suggestions are added or rescinded to work that the developers will have already started working on

B. What is a ticket?

A program/entity may make a request to the software development team for a bug fix, feature addition/removal/modification, replacement or any relevant software development task.  This request may be made by having a program representative filing a ticket or the software team lead filing the ticket on behalf of the program's representative. 

A program/entity issuing a ticket should review published tickets to ensure that this ticket is new and that a similar ticket has not been filed. If a similar ticket has been filed, a program/entity should append any unique and additional details as comments to this ticket's comment section

C. Ticket Structure

This ticket containing a software development task filed for implementation should have the following :

A definitive title briefly outlining what needs to be done, what components are to be affected this modification and the reason for this action 

e.g. Improve the search algorithm for the Patient Matching Module to reduce time taken to generate reports 

Type of Issue (JIRA already requires a user to select the type of issue before adding more details to it)

The type of issue can be 

  • Bug 
  • New Feature 
  • Improvement 
  • Task 

Priority of Issue 

The priority of an issue may be 

  • Blocker: Normal daily operations cannot proceed until this is addressed.
  • Critical: Seriously adversely affecting daily operations for multiple people
  • Major: Adversely affecting daily operations, workaround exists
  • Minor: May or may not be affecting daily operations
  • Trivial 

Build version that this issue affects 

Environment that the issue is found in 

Build version that will be affected by the issue 

A Description of the bug that should include the following information:

  • A context describing who the users of the module/current functionality are/will be and what the expected behavior is/will be. 
  • If the ticket being filed is a bug, describe how the produced behavior is different from the expected behavior and include a set of steps to reproduce the unintended behavior. Use charts & graphs, screenshots. mock-ups and wire-frames to definitively explain this section. Where possible, add a link to the source code where this behavior is implemented. Do not add/copy-paste the code to the ticket description.
  • If there has been a discussion on IM, email, Google Groups or any collaboration platform, add a link to this discussion to this ticket description.
  • Add a set of scenarios as acceptance criteria to the ticket description. 
  • Add contact information to the person/entity making the request. This may be in the form of a JIRA account name, email address or social media account name.

Below are few examples of well defined comprehensive tickets.

  1. PCSMOD-43 - Getting issue details... STATUS
  2. MUZIMA-25 - Getting issue details... STATUS
  3. MUZIMA-24 - Getting issue details... STATUS

Things to adopt while filing tickets 

  • Ensure that all tickets fall within and reference an Epic or user story
  • Ensure that ticket follows the structure specified above
  • Break down the tickets into a number of distinct sub tasks that translate to the milestones for a specific ticket. Note that JIRA does not allow one to create a sub-task from a sub-task.
  • Use labels to indicate other projects/modules/areas affected by the ticket. For example, if a ticket is under "AMRS Issues" project, you can put it a label "fct-highest-priority" to indicate it is highly important in FCT work.

Things to avoid while filing tickets  

  • Do not list out a software development ticket request title or description as a suggestion or using a tone implying that you are making a suggestion. Do not use a software development ticket to discuss/evaluate/build an idea. A software development ticket is a statement making a formal request for some sort of software development task. Use alternative channels to further develop your software development idea/task before inserting the finalized concept into JIRA as an idea.

For Example

I think that the search engine algorithm should be improved to reduce the time taken while generating reports 

Instead write this as 

Improve the search algorithm for the Patient Matching Module to reduce time taken to generate reports 

  • Avoid the use of terms that may lead to ambiguity such as 'it'. Replace these terms with the actual module, features or entities that you are referring to. 
  • Avoid cross posting tickets on both the AMPATH and OpenMRS JIRA. These two platforms while offering similar functionality have different targets for implementation. The AMPATH JIRA lists software development requests for AMPATH related tasks (mostly on AMRS) while the OpenMRS JIRA lists software development tasks for OpenMRS core changes. 
  • Do not add source code to a ticket's description, title or comment. Instead insert a link to the source code repo for review. This allows one to extend the source without making modifications to the tickets and limits the glut visible to every ticket. 


  • No labels

1 Comment

  1. Bug description template:

    h5. Context
    Describe the background and context here.
    h5. Steps to Reproduce
    # First step
    # Second step
    h5. Observed Behavior
    Describe precisely the behavior observed here.
    h5. Expected Behavior
    Describe what you expected to happen here.


    Improvement or task description template:

    h5. Context
    Describe the background and context here.
    h5. Requirement
    Describe the requirements here.
    h5. Acceptance Criteria
    * Describe first criteria here
    * Describe second criteria here