Date: Fri, 29 Mar 2024 10:55:48 +0000 (UTC) Message-ID: <1624698625.11607.1711709748415@aws-us-west-2-edgex-confluence-1.web.codeaurora.org> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_11606_1858167173.1711709748415" ------=_Part_11606_1858167173.1711709748415 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
As activity in the EdgeX Foundry project has increased, it has been incr= easingly difficult for interested stakeholders to comprehend the progress t= hat has been made towards a particular release and the work that it still o= utstanding. The Linux Foundation does not supply a standard set of pr= oject management tools that could be used for this work and a free-to-use f= or open-source commercial tool has not been identified. Consequently,= the project has decided to settle on=E2=80=94for now=E2=80=94the free tool= s that come with GitHub. Unfortunately, the tools that come with GitH= ub provide only mechanism and no policy:
Figure 1: GitHub New Issue form and GitHub-supplied documentation
This document proposes a project and issue management standard for use w= ithin EdgeX community. It is written from a data quality perspective: actio= nable data is high-quality data. High-quality data demands documentation of= the business process around the data and providing clear definitions as to= what the data means and how it is used. High-quality data requires that pa= rticipants opt-in to these definitions and take an active role in ensuring = that the data in the system is managed in compliance with the standard.&nbs= p; It will then be possible to build reports on top of the underlying data = to provide an accurate representation of the state of the project at any gi= ven time.
In order to achieve the high data quality needed for reporting and proje= ct management purposes, the project must attach meaning to the various fiel= ds and the participants must be disciplined in their issue management proce= sses. For example, here is the new issue form (Figure 1) with more me= aningful descriptions:
Figure 2: GitHub New Issue form with more meaningful data definitions
Definition: Issue is an umbrella term that represents l= ifecycle-managed textual discussion about the GitHub-hosted software and do= cumentation. An issue can be used to discuss planned work, software d= efects, questions about the product, or other textual discussion. Iss= ues have fields and metadata associated with them that can be used for filt= ering or searching, and have lifecycle information where the lifecycle of a= n issue terminates in a "closed" state. Issues are not code.
Definition: Pull Request contains all the fields of an = Issue, but additionally a reference to code that is being proposed for deli= very to the Git repository.
The fields in GitHub issues and pull requests mean the following in the = EdgeX Foundry repositories:
Field |
Definition |
author |
An audit field that is automatically set to t= he creator of the issue or PR. |
title |
A brief summary of the contents of the issue = or pull request
Business rules: =C2= =B7 Required always |
description |
The first comment box after the title is the = description. It provides the long description regarding what the issu= e or pull request is about. For pull requests, the description contai= ns the body of the commit message and additional metadata used by GitHub fo= r automation purposes, such as "Fixes #" tags.
Business rules: =C2=B7 Requi= red always |
comments |
Every comment box after description forms a r= unning log of the community discussion of the issue or pull request. Diagno= stic information from automation or bots may appear in comments as well. |
assignees |
If assigned, the assignee has assumed respons= ibility and is the point of contact for coordinating work on the issue.&nbs= p; The assignee must be a project member. For pull requests, this fie= ld has no special meaning: if set, it is usually set to the author. <= br> Business rules: =C2=B7 = Required for all in-progress issues =C2=B7  =
; Recommended for all release backlog issu=
es |
reviewers |
(Pull requests only.) List of project members= who are solicited to review the pull request. |
labels |
Labels are used to implement virtual fields.&= nbsp; See "Virtual Field Definitions" below. |
projects |
Projects are used by EdgeX working groups to = subscribe to the status of an issue on their project board. One of these wo= rking groups is responsible for managing the Issue through its lifecycle. A= n Issue may be on multiple boards simultaneously. |
milestone |
All milestones in EdgeX refer to releases.&nb= sp; The milestone field is used to include the issue in this release's back= log. It indicates a commitment to resolve the issue by the named mile= stone. (For retroactive milestones, it would be used to flag the issu= e as "wontfix".) Milestone is a single-select field: only one milestone can= be selected at a time. |
Table 1: Issue and Pull Request Field Definitions
The "labels" field is used to implement virtual fields. All virtua= l fields are optional unless otherwise specified. Th= ese are defined as follows:
Virtual Field |
Definition |
issue_type |
Indicates the type of issue (single-select):<= /p>
Business rules:
|
close_reason |
Explains why an issue was closed (without a f= ix) (single-select):
Business rules:
|
subsystem_affected |
Indicates the scope of the proposed change (m= ultiple-select):
|
release_affected |
A multiple-select field used for bugs only th= at indicates a release of EdgeX which is affected by the issue. Note, there= may be multiple release_affected labels if the issue exists in more than o= ne EdgeX release. For feature development work, the milestone field i= s the official field used for release planning. (This changes the current p= ractice so there will be a transition period where both fields are used.)&n= bsp; If multiple release_affected tags exist and the issue is only fixed in= one of these releases resulting in the issue being closed, if any of affec= ted releases is either an active development release or an LTS release, the= n a new issue should be opened with release_affected set accordingly. This = allows the issue to continue to be tracked in the other affected releases w= here it makes sense to do so. Values:
Business rules:
Exceptions:
|
exception |
Indicates an exceptional condition outside of= the normal workflow (multiple-select):
|
priority |
Priority is used to influence where to put re= sources and what features to cut when a release window is closing (single-s= elect). The permissible values for priority and suggested guidance ar= ound their usage are:
|
Table 2: Virtual field definitions
There is no "status" field in GitHub. Issues are either "open" or = "closed". However, issues may be assigned to project Kanban boards an= d can be moved from column to column in order to provide advanced status re= porting. The current column of an issue is represented below as "stat= us." Issues may freely move from state to state without restriction.&= nbsp; Moreover, each working group may have its own customized state machin= e. The table presented below is the project-recommended values. = Unless otherwise specified, issues must be manually moved from state to st= ate.
Status |
Meaning |
new issue |
Default state for incoming issues when assign= ed a project. New issues require triage into either "icebox" or "rele= ase backlog" status. |
icebox |
There are no current plans to work on the iss= ue in the near-term. |
release backlog |
The issue is planned for the upcoming release= or be retroactively fixed for a previous release. |
in progress |
Someone has started working on the issue <= p> |
QA/Code Review |
A state reserved for pull requests that have = not been approved. GitHub automation automatically places new pull re= quests here. |
Done |
Terminal state for all issues and pull reques= ts. GitHub automation will move issues and pull requests here automat= ically when they are closed. |
Table 3: Project-recommended issue status values
Figure 3 below shows the idealized state machine for issues. This = is the recommended flow but working groups may customize this flow to one m= ore suitable for their unique requirements.
Figure 3: Idealized state machine
When a bug affects more than one release, multiple issues shall be filed= , one against each affected release. (Typically, this will be against= the current supported release and release-in-progress.)
The following issue fields should be set:
If the bug is not going to be fixed in a particular release, the close_reason should be set to wontfix and an app= ropriate comment made as to the reason the bug was so dispositioned. = Bugs that will be fixed should go through the normal bug handing process.= p>
Release stabilization is the period of time between code freeze (when a = git branch named after the release is made) and when the official EdgeX rel= ease is declared (container images and snaps published). During release sta= bilization the following procedures apply:
The procedures for "Bugs affecting more than one release" should be used= for the associated bugs.
The project management system draws on the high-quality data of the issu= e management system. The project management system is designed to pro= vide high-level decision support for release activities, and to provide vis= ibility to interested stakeholders on the state of the project.
There are two primary mechanisms used for this:
GitHub milestones provide a public view of release progress and can give= a coarse approximation as to how close the project is to the next release = milestone.
For example, this what the GitHub milestone for Fuji release looked like= in the week following the Geneva planning face-to-face.
<= /p>
Contrast this to the GitHub milestone for Geneva at approximately the sa= me time:
One problem with GitHub milestones are that they are tracked on a per-re= pository basis. Since an EdgeX release is made of code form multiple reposi= tories, looking at a single repository's milestone, such as edgex-go, is in= sufficient to get the health of the entire project.
Something more is needed.
GitHub provides a facility called a "project" that allows for organizing= work. These projects can be created at a per-repository level or at = the organization level. The project boards function as a Kanban, whic= h customizable swim lanes and some basic automation for state transitions b= etween swim lanes. In the Issue Management section we talked about how thes= e project board are used to implement a more granular issue state machine t= han "open" and "closed." In this section, we describe how these board= s are used for project management.
The following project boards have been created at the organization level= :
These project boards map 1:1 with the standing EdgeX working groups wher= e contributions to the code base are coordinated.
The overall project state can be ascertained by navigating to each of th= e above project boards and counting the issues in each column.
Figure 4: Project board standard swimlanes
The project is ready for code-freeze when the "release backlog" is empty= , and there are very few issues remaining in the "in progress" and "QA/Code= review". The project boards should remain in this state until the re= lease is cut.
At the time of code freeze, the project boards should resemble the follo= wing state. Notably, the backlog should be empty, and the project sho= uld only be working on bug fixes for the impending release. The proje= ct may stay in this state for several as the entire framework is regressed = and bug fixes made.
<= /p>
After code-freeze, it is technically possible to begin making changes fo= r the next release. This early work should be done by directly pickin= g items out of the "icebox" and putting them into "in progress." It i= s expected that as the project matures in its release practices, the durati= on the uncomfortable state between code freeze and release will shorten fro= m several weeks to several days. There is no good way with the curren= t tools to filter the project boards based on release.
A new release cycle is started by an announcement that the official rele= ase has been made.
At the beginning of a release cycle, working groups pull selected backlo= g from the icebox into the release backlog. This backlog is presumed to hav= e been groomed prior to the planning face-to-face and ratified there, then,= when the release branch for the previous release is made, the done items f= rom the previous release are archived, and the backlog for the next release= is pulled into the release backlog column:
From this point forward, issues gradually transition to the "done" state= :
<= /p>