Software Development Methodology

Table of Contents

Agile Process

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.

Sprints

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. 

Sprint Planning

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.

Task Board

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.

Sprint Review / Showcase

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.

Retrospective

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.

Jira Tickets

Why do we use tickets?

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 

  • Clearly defining expectations
  • Measuring velocity
  • Coordinating work
  • Historical reference

Ticket Types

Reference the following definitions when determining what type of ticket to create in the OpenLMIS project.

TypeDefinition
BugA 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  OLMIS-3312 - Getting issue details... STATUS as an example Epic focused on making performance improvements for the 3.2.1 release)
StoryAn 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.
TaskA 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 FeatureA new feature to OpenLMIS which doesn't need to be expressed as a user story.
ImprovementAn enhancement to an existing feature in OpenLMIS. Can sometimes be confused with a new feature.
TestA manual Zephyr test case (these are created by Zephyr plug-in and linked to Stories/Bugs/Tasks).

Ticket Field Guidelines

Reference the following guide to understand what type of information should be captured in the ticket fields for the OpenLMIS project.

FieldDefinition and Guidelines
Project 
The parent project to which the ticket belongs. Use 'OLMIS' project for OpenLMIS 3.
KeyAn 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).
SummaryA 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.
TypeA category for the ticket, like "Task", "Epic", or "Bug". See above for a list of types in the OpenLMIS project.
StatusThe 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.

  • Blocker = done first
  • Critical = must be finished
  • Major = standard/default
  • Minor = nice to have
  • Trivial = not necessary 

See Prioritizing Bugs section for guidance on bug prioritization. 

Affects Version(s) 
(if applicable)

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:

  • Administration - tickets concerning Administration screens
  • CCE - tickets connected to CCE service
  • Documentation - ticket that are about adding/fixing documentation
  • NeedsAcceptanceCriteria - for marking tickets that still need Acceptance Criteria
  • NeedsDiscussion - for marking tickets that solution still need discussion
  • Performance - tickets that are related to performance improvements or bugs
  • NeedsPerformanceCheck - ticket for making/fixing performance test and finding/solving performance issues
  • Management - tickets that the Product Manager, Community Manager and Architect use to track decision making and documentation.
  • Phase1Bug - label for bugs from 1st phase of Regression Testing
  • QuickWin - tickets that can be easily/quickly done. Great tickets for new contributors/developers to work on.
  • Regression - for marking bugs which are for fixing previously working feature 
  • Reports - for marking tickets about reporting
  • Requisitions - tickets connected to Requisition service
  • GapAnalysis - tickets within the scope of the Gap Analysis Development Project
  • Stub - tickets without description
  • TechDebt - ticket for paying technical debt
  • Translation - ticket to track translating of messages in Transifex. 
  • UIChange - tickets which either change (or add new UI features) UI in the latest release. For example, if the ticket adds a new button or changes an existing button that ticket should have the UIChange label. Product Committee and Release notes use this label to monitor changes and new features which users will see when upgrading to the next version.
  • Vaccines - tickets from scope of Vaccines features
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

  • User story (As a User Persona, I would like <action> so that <business reason>). 
  • Acceptance Criteria (Acceptance Criteria is leveraged both for development and testing purposes so please include an appropriate level of detail) 
  • Background information and reference materials (mockup/screenshots/etc) to provide appropriate context. Please include within the description and not within the comments or attachments. 

For bugs, please reference our guidelines here.

LinksA list of links to related tickets, wiki pages, or google documents. (Strikethrough text, like this, indicates that a ticket has been resolved (either Done or Dead).)

Assignee (if applicable)

The person to whom the ticket is currently assigned. Note that you cannot assign tickets to a user group.
ReporterThe person who entered the ticket into the OpenLMIS project. (Automatically set by Jira.)
VotesThe number shown indicates how many votes the ticket has.
WatchersThe 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.)
CreatedThe time and date on which the ticket was entered into Jira.
UpdatedThe time and date on which the ticket was last edited.
ResolvedThe time and date on which the ticket was resolved.
EstimateThe 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.)
RemainingThe 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.)
LoggedThe 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.

Ticket Workflow

StatusDefinition
RoadmapTickets 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 DoTickets 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 ProgressMeans that active development on the story is underway. May be thought of as synonymous with "In Development." 
In ReviewMeans 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.
QAMeans 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.
DeadThe 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.



Definition of Done

Definition of Done (DoD) is an agreed-upon criteria for when a Story or Task may be closed*.   A Story is Done when: 

  1. The functionality described in the story was implemented (or bug fixed) according to the provided acceptance criteria or reproduction steps.
  2. Unit tests are written for any new code.
  3. Updated RESTful interfaces are included in test automation.
  4. Code has been committed to the development branch and builds clean on CI server (including tests and static code analysis)
  5. Code has been peer-reviewed by at least one person who wasn’t directly involved in the development and the code review feedback was addressed.
  6. Story has been reviewed via the TEST or UAT build (not on a dev box!) and the summary of the conducted tests has been attached to the ticket.
  7. No open “Blocker” or “Critical” bugs are open on the story (e.g. bugs found during testing).
  8. CHANGELOG entry is added for all services impacted during work on the ticket.


Definition of Done (DoD) for Bug is following:

  1. 1-7 from above apply.
  2. New unit tests are added that wouldn't pass before fix, if possible.
  3. Bug root cause analysis is done and Bug Root Cause Analysis page is updated.

 *The DoD may not apply to all stories.  E.g., a Story to write a design does not need code review.

Edge Cases

For information on how to document edge cases please head to Identifying and documenting edge cases for new features 

Future Ticket Guidelines

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

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.

Components

Starting with the micro-service architecture of v3, we are dividing work along Component boundaries and identifying Component Leads.

Component generally meets this definition:

  • It has its own Git repo
  • It 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 Lead or Leads may be assigned to any Component to fill this role:

  • The Lead(s) look out for the long-term quality and correctness of their Component
  • Lead(s) may be identified both at VillageReach and within the software development team (e.g., SolDevelo)
    • The VillageReach Component Lead helps with backlog grooming for the Component, and works with the Product Owner to translate requirements into specific tasks that the developers can take action on
    • The Component Lead with the software development team helps guide the development efforts as they build the Component
  • If one component or team needs changes to be made in another component/by another team, the Component Lead(s) are the right people to contact in order to make the needed work happen on their component
  • The Component Leads look out for the the API (and RAML), the Contract Tests, and generally for how their component interfaces with outside consumers

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.

Meetings

Backlog Grooming (aka Backlog Refinement)

  • When: Each team holds their own backlog grooming at least once per sprint
  • Leads: Team Leads
  • Participates: Product Owner, Team Leads + chosen team members, Scrum Master(s)
  • Duration: No more than 2 hours 
  • Objective: Review the high-priority tickets and/or discuss what the next sprint should focus on. The product owner will highlight the functional priorities and the tech leads will highlight the technical priorities.
  • Meeting InviteOpenLMIS v3 Backlog Grooming.ics
  • Notes: Meeting notes are located in Backlog Grooming

Sprint Planning

  • When: Each team holds their own sprint planning at least once per sprint, before the new sprint starts.
  • Leads: Team Leads
  • Participants: Entire team
  • Objective: Review prioritization of tickets, plan out the sprint. Estimate stories, story points decided by using Planning Poker using Fibonacci numbers. Tickets that are pulled into the sprint will be located on the Jira sprint board for each team.
  • Sprint duration: 2 weeks

Daily Scrum (aka Stand-up)

This is a suggested meeting arranged and held separately by each team.

  • Participants: Team members
  • When: Daily (either online or by conference call, depending on the team)
  • Objective: Each team member shares what they worked on yesterday, what they will work on today and if they are waiting on anything or blocked.

End of Sprint Review/Showcase

  • When: 6:00 - 7:30am Pacific every other Wednesdays, no more than 2 hours (see Project Management for times and meeting connection info)
  • Lead: Wesley Brown facilitates; Leads and Devs showcase their work
  • Objective: Showcase tickets completed during the last sprint and allow team members to ask questions and review work.
  • Before the meeting, the Leads help team members identify key stories to be demonstrated.
  • Stories/Issues/Tickets updated and carried over as necessary.
  • At the end of every sprint, each team shall measure and record its velocity (expressed in Story Points)
  • Notes: Recorded and published for the community under Sprint Notes

Sprint Retrospective

  • Participants: Scrum Master(s), Team Members, Product Owner
  • When: Typically held after the Sprint Review by each team independently
  • Optional, for each team to decide when or how to conduct this
  • Objective: Focus on process: 
    • What is working well? 
    • What could be improved

Gap Project Scrum Meetings

Team Lead/Scrum Master tasks are located here.

 

OpenLMIS: the global initiative for powerful LMIS software