[Proposal] GitHub Usage and Process

[EisenbergEffect]

As previously discussed, I've been taking a look at our issues, milestones, labels, projects, etc. and have put together a set of recommendations.

GitHub Specifics

Milestones

Our current set of milestones are out of date. My recommendation is to close out all of our existing milestones. Going forward, we can center milestones around particular major features or innovations. Some milestones might be "Router v1", "New Provider Infrastructure", "Fluent UI Refactor", etc.

Labels

I took a look at our existing set of labels, as well as the labels used by Aurelia and .NET, to get a survey of different patterns being used. I like some of what @awentzel put in place for our labels and think we can benefit from making further use of what's there. I've pulled some ideas from Aurelia and .NET that have the notion of "topics" or "areas" as well. Here's what I've come up with by doing a bit of cleanup/consistency work on our own labels and combining that with the area idea.

Issue Types

Each of these labels will have a distinct color and is based off of our current conventional changelog git commit types. Every issue should receive exactly one of these labels as part of the triage process.

• bug
• feature
• improvement
• chore
• docs
• rfc
• spec
• investigation

Issue Status

All of these labels have the same color and represent the status of the issue. Every issue should receive at least one of these labels as part of the triage process. The status:triage status is special. Each newly created issue should start out in this state but should not remain in this state after the triage process is finished.

• status:triage
• status:needs-information
• status:needs-investigation
• status:blocked
• status:under-review
• status:planned
• status:in-progress

Issue Areas

All of these labels have the same color and represent the area of the codebase or conceptual feature-set that the issue is related to. As part of the triage process, an issue should be given at least one area label.

• area:fast-element
• area:fast-foundation
• area:fast-components
• area:fast-components-msft
• area:tools
• area:dev-ops
• area:cloud

Community Labels

All of thees labels should have the same color and can optionally be added at any point prior to closure to signal the community of special opportunities to contribute.

• community:good-first-issue
• community:help-wanted

Issue Closure

All of these labels have the same color and represent the reason why the issue was closed. When an issue is closed, its status label(s) must be removed and at least one close label should be added.

• closed:done
• closed:by-design
• closed:duplicate
• closed:no-repro
• closed:obsolete
• closed:stale

Projects

I recommend that we begin using GitHub projects more to track our backlog priority and in-progress work. To do this, I think we can just clean up the projects we have a little bit and have something we can work with. I recommend we go with the following set of initial projects:

• Architecture - Track core architecture and capabilities work primarily in fast-element and fast-foundation
• Components - Track work on new components or fixes/improvements to existing components. This is likely to span across fast-foundation as well as the design system packages.
• Design Systems - Tracks core work on design systems in fast-foundation as well as design-system-specific work in their packages.
• Tooling - Tracks work on our core tools as well as 3rd party tool plugins (e.g. Figma)
• Documentation - Tracks work on the documentation.
• Plugins - Tracks work on optional packages such as a future router, dependency injection, etc.

Issue Templates

We can create a few more issue template options, aligning with the basic issue types listed above.

• bug
• feature or impreovement
• chore
• docs
• rfc
• spec
• investigation

Pull Request Templates

Right now we have a single PR template that is used. We can split this out into multiple templates, which would make certain scenarios such as spec PRs or component PRs more clear. The following templates are my recommendation:

• bug
• feature or improvement
• component
• chore
• docs
• spec

Process Summary

At the highest level, our team strategic planning meetings will identify our milestones. We may also choose to create special project boards, depending on the size or priority of the work.

Issues will either be created by us, in which case they can have labels immediately assigned and be prioritized in any related boards.

Or the issues will be created by the community. Each morning someone can triage the new issues. GitHub will add the status:triage label for us, so it will be easy to locate issues that need to be triaged. Once an issue is triaged, the person responsible should note if there are any issues that require immediate action. Examples are:

• needs information - follow up briefly with the issue reporter to get information
• security/privacy/accessibility issue - follow up with lead to discuss and determine if current work should be interrupted to address

If the issue does not represent an immediate need, then the team member should make sure to put an appropriate status. Anything tagged with status:under-review, status:planned, or status:blocked can be prioritized as part of the team strategy meeting.

We can rotate issue triage across the team, by assigning a particular day to each person(s). (I'm happy to do the first several rounds myself in order to get existing issues cleaned up.)

Each sprint we'll pull issues from the ordered backlog, assign them to team members and mark them with status:in-progress. When the issue is resolved, it can be tagged with a closed label.

Open Questions

• Do we want to do estimation as part of the backlog grooming process? If so, what is the best way to do that on GitHub? Should we just add a comment with the estimate? Should we have a set of labels based on an abstraction (xs/s/m/l/xl or fibonacci days .5,1,2,3,5,8,13)
• If we do estimation in GitHub, is there an easy way to measure our agility so that we can improve the accuracy of our sprint commitments over time?

[awentzel]

@EisenbergEffect, I love it! A couple notes. How should we track my focus on Azure cloud architecture, compliance (privacy, security, a11y), and operations which make up all of my work. I did see DevOps label. Would it all go in there? Infrastructure versus operations? Would my architecture fit under project architecture?

I also would love Fibonacci estimates as well as actual so we can improve planning and decision intelligence moving forward.

[EisenbergEffect]

@awentzel We could track under area:devops or also add an additional area to distringuish, such as area:cloud.

[awentzel]

@EisenbergEffect let's try for area:cloud and see how that works out. I also, think it's worthwhile to place this in the documentation for new contributors.

[radium-v]

Could we add a type like "improvement"? for something that falls between a bug and a feature.

[EisenbergEffect]

@radium-v That makes sense. So, things like perf optimizations, internal changes that don't add new features but make things better, etc.

[EisenbergEffect]

I added the label for improvement. I think we can use the same PR and issue template for feature and improvement possibly. We'll see.

[awentzel]

@radium-v That makes sense. So, things like perf optimizations, internal changes that don't add new features but make things better, etc

My definition of feature is anything not a bug. So optimizations or improvements to features seems like it's still a feature work. Which is why adding "add, update, remove" as a prefix to the title was useful to distinguish type of feature work. How would this aspect change?

[chrisdholt]

@awentzel, I think it'll be difficult to stay on top of updating ppl's issues to include different language (add, update, remove). I think the label can help represent that without having to edit/update language of specific issues. The label would articulate the intent at a glance. Feature v. Improvement are markedly different in that all improvements would be on top of something existing - there's also an inferred difference in priority as well between the two.

[awentzel]

@chrisdhold my thought and vision on the title is based on readability of the changelog, not the PR process. One day we will have the ability to present a roadmap and changelog with filtering so it's beautifly easy to read and understand. Title prefixes help with consumption of that information, imho.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.