Table of Contents
Development of OpenLMIS 3 happens with multiple teams working in a scaled agile approach. We aim to follow the Principles for Digital development, including the principle 'Be Collaborative'. We strive for the teams to be 'loosely coupled but tightly aligned.'
All teams share some common communication and process elements to enable global collaboration: all teams use the same project management tool (the publicly accessible OpenLMIS Jira site); all teams hold public Showcases which are recorded; and we ask each team to hold their own daily stand-ups, planning and retrospective meeting for each sprint.
The workflows described on this page represent the current community practice, and we are flexible to change these. Individual teams may customize this workflow as long as they are delivering value and providing consistent, open communication with the OpenLMIS community.
OpenLMIS follows a basic agile sprint cycle, and we encourage those new to agile to purchase the 40-page $1 ebook, Scrum. Most teams operate on a 2-week sprint cycle, though 1-week sprints have been used sometimes.
Before an individual team holds its Sprint Planning, the Product Manager updates the Product Backlog based on input from stakeholders including the Product Committee. We may create a "Backlog" wiki page or use the Jira backlog to communicate priorities from the global Product Manager to the specific team. The team can hold Sprint Planning on their own, and often asks questions about tickets using Slack or by scheduling a "Sprint Q&A" meeting to discuss questions.
We require all teams to use the OpenLMIS Jira site to track tickets in a visible, consistent way that allows community input. To facilitate ticket use and collaboration across teams, we do ask for consistent use of the ticket Status and ticket Type. Different teams use Labels differently or may include different standard information inside ticket descriptions.
We require all teams to attend a Showcase meeting to present their work at the end of each sprint. This is public and is recorded for the OpenLMIS community. See Project Management for meeting connection info.
We ask each team to hold a Retrospective at the end of each sprint. We value continual improvement, and it's important to talk about what we need to improve. Each team holds this on their own retrospective, and shares notes in the OpenLMIS wiki (eg under Retrospectives).
We have used the following slide deck to explain our agile process to new teams.
OpenLMIS uses Jira tickets to define, track and historically reference. These tickets serve as a contract of what is being completed and will be referenced historically as a source of truth of what was completed. We believe that using tickets to track work provides value by
Reference the following definitions when determining what type of ticket to create in the OpenLMIS project.
Type | Definition |
---|---|
Bug | A defect which impairs or prevents the functions of OpenLMIS. (See Reporting Bugs for details on examples and how to file a bug) |
Epic | Large piece of work that encompasses many Tickets (mainly Stories). Epics should not span multiple releases. Epics should deliver value to the user and be expressed as a user story that needs to be broken down. (See OpenLMIS 3.2.1 Performance as an example Epic focused on making performance improvements for the 3.2.1 release) |
Story | An OpenLMIS functionality request expressed from the perspective of the user (use User Personas). Ideally a user story is the smallest unit of work that needs to be done. |
Task | A task that needs to be done. May or may not provide direct value to users. Frequently tasks are categorized as technical debt or documentation. |
New Feature | A new feature to OpenLMIS which doesn't need to be expressed as a user story. |
Improvement | An enhancement to an existing feature in OpenLMIS. Can sometimes be confused with a new feature. |
Test | A manual Zephyr test case (these are created by Zephyr plug-in and linked to Stories/Bugs/Tasks). |
Reference the following guide to understand what type of information should be captured in the ticket fields for the OpenLMIS project.
Field | Definition and Guidelines |
---|---|
Project | The parent project to which the ticket belongs. Use 'OLMIS' project for OpenLMIS 3. |
Key | An auto-assigned unique identifier for the ticket. For example, OMIS-304 (The characters to the left of the hyphen represent the project the this ticket belongs to and the numbers increase sequentially). |
Summary | A brief, one-line summary of the ticket. For example, "Ability to hide products on the requisition form." This line should summarize the ticket so a person could read and understand the main point of the ticket. |
Type | A category for the ticket, like "Task", "Epic", or "Bug". See above for a list of types in the OpenLMIS project. |
Status | The stage the ticket is currently at in the ticket workflow. See below for a list of statuses. |
Priority | The importance of the ticket in relation to other tickets. All tickets are placed in descending order, using JIRA's "Rank" feature, so if two stories are both 'critical' the story on top is priority. The following prioritization applies to non-bug tickets.
See Prioritizing Bugs section for guidance on bug prioritization. |
Affects Version(s) | Project version(s) for which the ticket is (or was) manifesting. For example, '3.1.2'. |
Fix Version(s) (if applicable) | Project version(s) in which the ticket was (or will be) fixed or in which the feature is introduced. For example, '3.2.3'. |
Component(s) | Project component(s) to which the ticket relates. See the section below for more information on Components. Usually defined as: having its own Git repo; is an independent piece of the software with its own boundaries, own version number and dependencies. The build/distribution system includes a component into a working OpenLMIS distribution/implementation. A separate group of developers may have 'ownership' over the component. Component definitions and leads outlined here. |
Labels (if applicable) | Labels categorize and can group related tickets. For example, tickets related to the Vaccine MVP set of features are tagged with "vaccine". Existing labels:
|
Environment (if applicable) | The hardware or software environment to which the ticket relates. |
Description | A detailed description of the ticket. For stories, please include a minimum of the following pieces of information
For bugs, please reference our guidelines here. |
Links | A list of links to related tickets, wiki pages, or google documents. (Strikethrough text, |
Assignee (if applicable) | The person to whom the ticket is currently assigned. Note that you cannot assign tickets to a user group. |
Reporter | The person who entered the ticket into the OpenLMIS project. (Automatically set by Jira.) |
Votes | The number shown indicates how many votes the ticket has. |
Watchers | The number shown indicates how many people are watching the ticket. |
Due (if applicable) | The date by which the ticket is scheduled to be completed. (OpenLMIS uses fixVersion but does not use Due dates generally.) |
Created | The time and date on which the ticket was entered into Jira. |
Updated | The time and date on which the ticket was last edited. |
Resolved | The time and date on which the ticket was resolved. |
Estimate | The Original Estimate of the total amount of time required to resolve the ticket, as estimated when the ticket was created. (OpenLMIS does not use Estimate data on all tickets; some teams/partners do track time inside Jira and this data is updated by a plug-in.) |
Remaining | The current estimate of the remaining amount of time needed to resolve the ticket. (OpenLMIS does not use Remaining data on all tickets; some teams/partners do track time inside Jira and this data is updated by a plug-in.) |
Logged | The sum of the Time Spent from each of the individual work logs for the ticket. (OpenLMIS does not use Logged data on all tickets; some teams/partners do track time inside Jira and this data is updated by a plug-in.) |
Development | Link to Github commits and Fisheye code reviews. |
Agile | Click the links here to view your ticket on the OpenLMIS Kanban/agile board. |
Status | Definition |
---|---|
Roadmap | Tickets which are not groomed or slotted for work. All new tickets will initially default to Roadmap. These tickets lack clarity and are missing Acceptance Criteria. Tickets in Roadmap will not display in active sprints nor the "OpenLMIS General" board or backlog view. |
To Do | Tickets ready to be worked on (not yet started) and ready to be prioritized. These tickets will display in the "OpenLMIS General" board and backlog view. |
In Progress | Means that active development on the story is underway. May be thought of as synonymous with "In Development." |
In Review | Means that a Lead (component or team) is reviewing the ticket's implementation. These reviews are intended to verify the design and integrity of a work product, and should not be confused with code-reviews (which are described here). It is expected that all stories will progress through this state prior to being completed or moved to Done. |
QA | Means that manual Quality Assurance is occurring. The QA-person may move a story back to "In Progress" if they find bugs within its output. Developers and QA often work closely together to determine when a piece of functionality works as intended. |
Done | (See Definition of Done below). Done tickets should be assigned to the person that will showcase them - either the developer or their respective team lead. |
Dead | The ticket is no longer relevant and will not be worked on or implemented. |
During active development, each ticket is intended to progress chronologically through the statuses listed. The active development cycle pauses during the Release Process.
All new tickets created will begin with the Roadmap status to ensure appropriate grooming and prioritization. All tickets with a Roadmap status will be displayed on the Roadmap Board and not be displayed on the OpenLMIS General Board (see screenshot below) until tickets are groomed, clearly defined, and ready for work. If a ticket is ready for work at the moment of creation, the ticket creator can change the status to To Do to indicate work can begin on the ticket.
Once a ticket is set to To Do, it will be visible on the OpenLMIS General Board.
To Do tickets will be prioritized in the backlog and on the Backlog Grooming wiki pages. These tickets are considered on deck and ready for development soon.
Once a ticket is estimated and picked up by a developer, the Assignee will update the status to In Progress.
Certain tickets may not require a discrete QA step. For example, tasks dedicated to the creation of design artifacts (eg: sequence diagrams) would implicitly undergo QA by the person responsible for the "In Review" step.
While QA efforts (like the development of test plans) may occur in parallel with development, they may also have value even after a story has been deemed as "Done." (Regression testing, in order to ensure that subsequent work in additional stories have no adverse effect on the functionality implemented for earlier stories, is an example of such value.) For these reasons, as dedicated QA person may be assigned to a story within JIRA. This assignment may be kept throughout the story's lifecycle, and maintained even after a story has been marked as "Done."
When moving a ticket to a new status (eg: from "In Progress" to "Review"), the current Active Assignee is responsible for designating a new Active Assignee. Anyone who move a story to "Done" should set the Active Assignee to party who will showcase the ticket.
A Definition of Done (DoD) is an agreed-upon criteria for when a Story or Task may be closed*. A Story is Done when:
A Definition of Done (DoD) for Bug is following:
*The DoD may not apply to all stories. E.g., a Story to write a design does not need code review.
For information on how to document edge cases please head to Identifying and documenting edge cases for new features
Additional ideas for future improvements to these ticket guidelines include: Tags we use for important filtering (eg, Regression, Performance, etc); Share an example of a GREAT ticket or multiple tickets; and Links to any outside resources on good ticket writing that we might align with. See OLMIS-3361 for details.
Story points are not currently used the same way by each team. In 2018, we may try to align story points across teams to get more accurate data about individual team performance and overall OpenLMIS community velocity.
It is up to each team to decide what a Story Point is to them. Here is the current VillageReach dev team interpretation:
An "atomic" Story is one that is the simplest dev operation that requires touching the entire dev "stack" of work. Adding an attribute to a domain object is an example: it may take a small bit of design, code updating (Java/database/message properties, etc.) unit and integration testing and documentation. An atomic story is typically 1 point. We reserve 1/2 points for trivial Stories.
We generally recommend estimating story points by Planning Poker using Fibonacci numbers. The people making the estimate should be the actual team of staff who will be doing the work.
We use Story Points to power Sprint Burn-down charts in Jira to visualize progress of a sprint. We also use Story Points to measure longer-term work; EG, Vaccines Scope Progress or the Burn-up for 3.0 Release.
Keep in mind that teams should avoid a situation when the ticket's Story Points estimation is so high that it would require more then 1 sprint to finish it. In such case the ticket should be split into smaller tickets with lower estimation for each one.
Starting with the micro-service architecture of v3, we are dividing work along Component boundaries and identifying Component Leads.
A Component generally meets this definition:
A Component Lead or Leads may be assigned to any Component to fill this role:
Component Leads are documented on the Project Management page and in JIRA, where the Components page identifies each component along with one Lead (JIRA does not allow two Leads).
As we create and break down new tickets, we will start using the Component field intentionally to flag which component each ticket is for. Generally if a story spans multiple components (e.g. it has an API piece and a UI piece) we want to make separate tickets for each component and have the Lead(s) be involved in their piece. In the rare cases where we do not make two tickets, sometimes one ticket will have multiple components assigned to it.
Tickets that are for project management activities that don't touch any component do not need any component to be assigned. It's fine if those tickets have no component in JIRA.
This is a suggested meeting arranged and held separately by each team.
Team Lead/Scrum Master tasks are located here.