Public Backlog Proposal

• Proposal Status: Draft, In Review, Accepted, Rejected

How to read this document: Go to the workflow that suits you to see instructions for how to use the backlog. At the bottom of this document are risks, next steps, glossary, and the proposal research.

Prerequistes

Use the ZenHub browser extension or website and authorize ZenHub to your GitHub account. Visit one of our repos and click on the ZenHub tab to see the backlog.

ZenHub Workflows

Maintainer issue triage flow

1. New issues are labeled with "carvel-triage" and appear in the "new issues" column.
   1. If a comment is left in an issue that says a community member is working on it, move it to the "in-progress" column.
   2. If a PR is opened by a community member, 'ZenHub link' the PR to the corresponding issue if it exists, and move it to the "needs review" column.
2. Maintainer triages the issues. Once issue is triaged, add the label carvel-accepted.
3. Move the issue to "unprioritized backlog" column so that it can be reviewed and prioritized.

Community contribution flow

1. Please use the ZenHub browser extension or website and authorize ZenHub to your GitHub account. Visit one of our repos and click on the ZenHub tab to see the backlog.
2. To look for an issue to pick up, search for issues labeled with "good first issue" or issues in the "unprioritized backlog" column.
3. Please either add a comment in the issue saying that you are working it, or open a pull request and link it to the issue. A maintainer will add the issue to the appropriate "in progress" or "needs review" column. We may automate ths in the future.
4. The PR will be reviewed by a maintainer. If changes are needed, the issue will go back to the "in-progress" column. In the future we may move the in "in progress" PR back to the "unprioritized backlog" column if no work has been done in an amount of time.
5. Once a PR is merged, a maintainer will move the issue to the "done" column.

See what work will be in next release

1. Use the 'Repos' filter in the top left to filter by project
2. In the future we plan to use ZenHub "releases". Issues associated with a specific release will be included in that release. Once all issues associated with a release are done, we will publish that release.

Product priority flow

1. An issue starts in the "New Issues" column automatically.
2. Once an issue is selected for future work, it is moved to the "unprioritized backlog" column. The "unprioritized backlog" column is used for unprioritized issues or issues that need to be groomed.
3. Once an issue is ready to be picked up it is prioritized in ascending order in the "prioritized backlog" column.

Maintainer team contribution flow

1. Pick up the next thing in the "prioritized backlog" in my track. If I am a reviewer I use the "needs review" column to pick up work.
2. Assign self and pair to the issue.
3. Move card to "in progress".
4. If you want a review, submit a PR and 'ZebHub link' your issue to your PR. Move the issue into the "needs review" column.
5. If no review is needed, or the review has passed, the code can be merged, and move the issue to the done column.
6. Once a release is cut or the work is in production, the issue can be closed, ZenHub will automatically move it to the closed column.

Product velocity flow

1. Use the velocity tracking on zenhub to see team velocity.

Open Questions

• How to use use milestones. A milestone tracks velocity and seems to coorespond to a sprint.
• Where do we put discussion issues?
• How can we differentiate chores and features? We don't point chores, so how can we know what stories we want to point when the feature issues and chore issue look the same?
• How to specify what type of issue review that you want (code or functionality).
• How long should a PR that needs changes be in the "in progress" column before returning to "prioritized backlog" column?

ZenHub Glossary

Milestones

A Milestone is a collection of all the Issues that your team will do within a sprint ( typically a 2 week period). Milestones are used for short-term, fixed scope sprint planning. Milestones help teams track progress within a Sprint. Milestones are used to track team Velocity over time.

Releases

Releases are used for long-term, flexible scope, dynamically changing projects and committments. Releases help teams forecast deadlines and delivery dates.

Epics

A group of issues (stories) that may take a few sprints to complete. Similar to Tracker's Epics.

Pull Request linking system

GitHub's linking system in the sidebar of Issues and Pull Requests is separate from Zenhub's Issue <–> PR connection. The image below shows how to link a github issue with a PR via zenhub's connection feature and not GitHub's. This connection must be made from the pull request side.

Risks

For Github Projects and Zenhub:

1. Difficulty finding the backlog. The boards are not visible from the repositories.
   • Mitigation: Documentation on contribution
2. Timeline and velocity estimates may be inaccurate during the transition because we have access to different metrics.
   • Mitigation: Leadership knows and has expressed that the risk is acceptable.
3. Maintaining a backlog for public and a separate one for VMware confidential info may become confusing.
   • Mitigation: When someone puts an issue in tracker (confidential) a placeholder issue is put in the public backlog

Future Work

MVP for Next Community meeting

• I see a list of past iteration issues in the appropriate column in the backlog so that I can review stories at a high level from the last iteration.
• I see the next iteration issues in the "prioritized issues" column in the backlog and the stories are ready to be picked up.
• (BONUS) I see 0+ issues labeled with "good first issue" in the "unprioritized backlog" column so that a community member knows how they can contribute.

Future improvements

• Use automation to move cards to the next column when possible
• Automate moving community issues to the in-progress column once they begin work since they won't be able to edit the project board.
• Automate ZenHub and GitHub Projects to mirror each other so that those who won't use ZenHub can see it.

Research

GitHub projects

Pros

• Anyone can use it.
• Free

Cons

• Search functionality inside project is hard to use.
  • Filters on entire board also apply when searching cards
  • Query must use full repo name (repo:vmware-tanzu/carvel-ytt)
  • No suggestions in search
• No ability for blockers.
• The repos don't have links to the project board, seems like we have to go through the organization.
• No built-in velocity tracking
• Milestones and labels are the only way to group issues together.

Unknowns

• Ability to automate using Github actions

ZenHub

Pros

• May align with our current process smoother
• Has blockers (called dependencies).
• Can group issues with an epics.
• Can group issues with a release
• Built in option to apply point "estimates" directly to a issue.
• Shows up as a tab in each repo as long as the browser extension is installed
• Easy filtering by repo
• Free for public repos

Cons

• You must have a GitHub account and authorize ZenHub

Unknowns

• Velocity charts are dependent on sprints and milestones - unsure how helpful this metric will be in comparison to velocity from tracker.
• Does it cost money? -> free for public repos
• What automation does it have?

Tool Comparisons

GitHub issue triage flow

Github Projects	ZenHub
Issues are labeled with "carvel-triage". Maintainer triages the issues. Once issue is triaged, add the label carvel-accepted. Add the issue to unprioritized backlog column	New issues are automatically added to the New Issues Column. Triager triages each new issue in this column. When complete following the triage process, move the issue to the appropriate column. Usually this by labeling the issue with "carvel-accepted" and putting it in the unprioritized backlog column.

Community contribution flow

Tracker	Github Projects	ZenHub
None. It's private.	Look in "prioritized backlog" column. Optionally filter the cards by label like "good first issue", assign yourself to the issue and submit a PR when done. We will need a way to move the card to the in-progress column. When ready to review, move the card to "Review" column a maintainer will review, if the PR needs revisions the issue will be moved to the "in-progress" column. In the future a time limit will be set for in-progress issues.	Community members with github accounts who authorize zenhub to their account will be able to see our backlog. Issues in our [unprioritized backlog] labeled "good first issue" are ready and encouraged to be picked up. When ready for a review, the community member will move the issue to the "Needs Review" column.

Find what work will be in next release flow

Tracker	Github Projects	ZenHub
Chunks of work are grouped in epics. To see what will be in the next release you must look at all the stories that are prior to a release marker.	View the next milestone for a repo. All the issues in that milestone will be in that release. Alternatively, search for milestone name in project board.	Issues can be tagged with releases to show which release that work will be included in.

Engineering team contribution flow

Tracker	Github Projects	ZenHub
Pick up the Top of Backlog (TOB) for my track by "start"ing the story and noting owners. When the changes cause the tool to meet the acceptance criteria, "finish" the story and "deliver" it. If it does not need review, "accept" it. Otherwise, leave it in "delivered" and add a reviewer request. Once reviewed, if pass, "accept". Otherwise, "reject", and it goes back to TOB for the track.	Pick up the next thing in the "prioritized backlog" in my track. Assign self and possibly pair to the issue. Move card to "in progress". Either we finish the work and merge or we submit a PR to be reviewed. If we merge, close the issue, card should auto-move to "Done". If we PR, move card to "Needs Review". If changes are requested, move card back to "In Progress". If PR is merged, move card to "Done" (may be automatic)	Pick up the next thing in the "prioritized backlog" in my track. Assign self and possibly pair to the issue. Move card to "in progress". Once ready for a review, submit a PR and link your issue to your PR. If no review is needed, or the review has passed, the code can be merged, and the issue can be moved to the done column. Once a release is cut or the work is in production, the issue can be closed, automatically moving it to the closed column.

Product velocity flow

Tracker	Github Projects	ZenHub
Feature stories are 'pointed' in IPM for complexity. Tracker computes an estimated velocity to measure the average amount of story points you complete over a predetermined number of iterations. This measurement is used to predict team size and timelines.	No built-in way to point stories. The current strategy is to label the issue with a number corresponding to the point estimate made. Measurement of velocity would have to be computed by hand (may be possible to automate this with GitHub actions).	velocity tracking on zenhub. Metic tracking on Zenhub doesn't appear to be configurable, so we have to use one of their predefined metrics.

Product priority flow

Tracker	Github Projects	ZenHub
Stories created in the unprioritized backlog. During pre-IPM, the work gets prioritized and sorted by track. Prioritized stories are then reviewed with the engineering team during IPM and pointed for complexity.	An issue is created or triaged and has "carvel-accepted" that outlines some feature/bug/chore. The issue is labeled with one of feature/chore/bug. It is added to the "unprioritized backlog" column. The issue is reviewed by product and prioritized in the "prioritized backlog" column.	An issue starts in the "New Issues" column automatically. Once an issue is selected for future work, it is moved to the "unprioritized backlog" column. The "unprioritized backlog" column is used for unprioritized issues or issues that need to be groomed. Once an issue is ready to be picked up it is prioritized in the "prioritized backlog" column.