A comprehensive and systematic improvement to mapping and planning the Windows Community Toolkit

[Arlodotexe]

Background

Building 8.0 required us to juggle a lot of things, but balancing proactive and reactive planning and execution is always one of the trickiest parts of software development. For example, in the transition from 7.x -> 8.x, it would have made sense to at least assess and build a comprehensive and structured 7x project map that we could update as we ported things.

My responsibilities in the toolkit have primarily focused on building and maintaining infrastructure as the platform moves underneath us and as components move on top of us, recently with an increased focus on planning.

Some of our past planning choices have left us reactively putting out fires, eating up valuable time that should be spent planning to prevent fires in the first place. This is unsustainable-- eventually, the rate at which new "fires" occur will outpace the rate that you can put them out. Left unchecked, eventually you and your entire team will burn out.

We could be providing a better overall experience from end-to-end, everything from scalable planning and scalable task allocation to shipping code faster to actively combating and even reversing burnout.

Problem

Through hindsight, we've learned the value of foresight (the hard way).

We need a birds-eye view of the project, structured well enough to give us foresight even with limited or bottlenecked capability/capacity. The labels in the toolkit are insufficient to inform a full area-task mapping at a birds-eye view.

We need an improvement in both label coverage and structure. Tickets should be easier to handle all around-- creating tickets, finding tickets, planning tickets, allocating tickets, executing task tickets, and so on.

Solution

Upskill our labeling and planning capabilities so we can build a birds-eye view.

Build a birds-eye view

The full 7x and 8x map are being built, and the Project Area Mapping analysis linked below answers the questions needed to move forward building the map unabated.

Progress on the building of these area maps, as well as the area maps themselves, can be found at #602

Upskill labeling and planning capabilities

Of course, building such a comprehensive area map wouldn't be possible without first upskilling our understanding and strategies around project management itself.

Here's what we'll do:

• Standardize label mapping across repositories
• Identify coverage gaps and redundancies
• Remove obsolete labels
• Streamline ticket organization and discovery
• Provide an effective structure for multidimensional project management.

I've been using my free time over the last few months to build conceptual frameworks anyone can use to combat firefighting, manage burnout and slack, and map responsibilities to resources:

• WindowsAppCommunity/meta#1 Practical high-level organization of Areas and Tasks via Labels
• WindowsAppCommunity/meta#2 Balancing capability and capacity between individual and collective requirements
• WindowsAppCommunity/meta#6 Introducing the Area-Task Labeling Administration System: ATLAS
• WindowsAppCommunity/meta#9 Project Area Mapping: evaluating and planning component areas

These documents serve the necessary insights to guide scalable project management. They could be applied to the Community Toolkit or any other large-scale collaborative project(s) in the community.

Even with limited capacity, this should allow us to identify which combinations of what and where are bottlenecked so we can select the contributors most suited to take each ticket.

The plan is to manually leverage these insights and labels for now, but in the future any part of this could be turned into code.

Port existing Labels

Label Mapping Analysis

The existing labels used by the WCT, mapped to the labels provided by the ATLAS template.

WCT Label	Open Issues	ATLAS Label
accessibility ⚕️	9	areas::accessibility::*
blocked	4	n/a [deprecate]
bug	39	tasks::fixes::bug
CI/pipeline 🔬	1	areas::checks::ci
dev loop ➰	2	areas::processes::* + custom
DO NOT MERGE ⚠️	0	n/a [deprecate]
documentation	6	areas::docs::*
duplicate	0	n/a [deprecate]
enhancement	8	tasks::features::improvement
external ⬆️	2	areas::infra::dependency
feature request 📮	5	tasks::features::new
good first issue	7	capability::entry
help wanted	16	capacity::overloaded
invalid	0	n/a [deprecate]
low difficulty	1	capability::entry
need more info 📍	3	tasks::analysis::*
nuget 📦	0	areas::infra::dependent
Priority-1	8	n/a [deprecate]
Priority-2	1	n/a [deprecate]
Priority-3	4	n/a [deprecate]
question	2	tasks::analysis::clarification
regression	10	tasks::fixes::regression
sample app 🖼️	12	areas::docs::samples
testing 🏗	1	areas::checks::tests
Uno	4	dependency::uno
ux 🖌️	9	tasks::review::design
wontfix	0	n/a [deprecate]

Extending with additional labels

The labels provided by ATLAS serve as a template that can be extended as needed, which we need for the dependencies in the toolkit.

It starts to become unwieldy when grouping more than 3 label subtypes together into a single label.

To keep things somewhat tidy while retaining specificity, label extensions should use the last part of an existing 'standard' label.

For example, to add many specific areas::infra::dependency, you might use that tag as well as one of:

Label	Description
dependency::uno	Uno Platform, cross platform WinUI
dependency::winui2	The Microsoft.UI.Xaml nuget package for UWP.
dependency::windowsappsdk	A set of tools and libraries to facilitate developing modern Windows apps.
dependency::dotnet	A free, open-source, cross-platform framework.
dependency::xamlbehaviors	Common way of adding reusible interactivity to apps.
dependency::win2d	Immediate-mode 2d graphics rendering with GPU acceleration.
... and so on.

When extending the inbox labels, the general recommendations are:

• Focus on minimal and relevant extensions, ideally no more than 3 levels deep.
• Use consistent and well-isolated naming patterns that build on existing standard labels.
• Clearly document new extensions with examples and use cases.
• Consider the maintenance implications when adding new label categories.
• Periodically review to ensure extensions remain relevant and useful.

Deprecated WCT Labels

Some labels are better handled by GitHub's native features:

• DO NOT MERGE → Use Draft Pull Requests
• duplicate → Use GitHub's issue referencing
• invalid → Close with comment
• wontfix → Close with justification
• P1, P2, P3 → Create these as fields on GitHub's Project Boards

Recap, expectations

To recap, ATLAS provides us with a comprehensive and systematic approach to:

• Practical high-level organization of Areas and Tasks via Labels
• Balancing capability and capacity to prevent burnout and identify upskilling opportunities
• Allocating tickets to the most suitable contributors using area/task labels and capability/capacity indicators
• Mapping and planning out "Project Areas" for new or existing projects

This is what we've needed, and while it'd be ideal to adopt it reasonably soon there are undoubtedly additional considerations to address before we can fully lean into this.

For now, even without labels in place, this system serves to inform our mapping of 7x and 8x and the porting between them, the major and minor version updates, and a few other high-level planning details. However,

• With labels in place, it could inform everything between high-level planning and low-level execution.
• With processes manually implemented and solidified, we could reasonably scale to dozens of simultaneous contributors without bottlenecks.
• With processes implemented using automation or advanced tooling, we could reasonably scale to hundreds of simultaneous contributors without bottlenecks.

Closing considerations, open questions

Many (not all) additional considerations or open questions can be filed as tickets themselves in the WindowAppCommunity/meta repository, benefiting the other members of the community who have adopted it. Using a separate ticket also gives us extra space to flesh out the answer to even simple questions, as well as having easy follow-ups and discovery later.

These insights on project management benefit the entire community, so let's:

• Make sure it can be understood. We'll clear up any confusion and create FAQs as needed.
• Try to poke holes in it. We'll fix or refactor the system to accommodate as needed, maintaining the careful attention to detail.

There are questions we'll need to open and answer right away, such as compatibility with sites like https://up-for-grabs.net, but we're ready. Ask away and we'll triage and address.

[riverar]

Have you connected with the dotnet team for maybe some alternative simpler approaches? They have great momentum and are known to be very lean and mean.

[Arlodotexe]

Have you connected with the dotnet team for maybe some alternative simpler approaches? They have great momentum and are known to be very lean and mean.

@riverar I had done an "Evaluation of existing options and alternatives" over in WindowsAppCommunity/meta#6, but didn't include the approach used by the dotnet team.

Every team, including those spread across the community toolkit, uses a slightly different process and set of labels suited to their needs, though they all largely converge onto the same idea: splitting between "What" (Areas) and "Where" (Tasks). This is the core idea I've locked onto when building out the ATLAS labels-- the hierarchy is partially ordered, sparsely accessible via wildcards across GitHub, and is kept minimal and extensible. Much like a good code library.

For now, we're only looking to improve our labels to a point where we can create Project boards with the flexibility needed across areas. For example, we'd like the ability to create dedicated project boards:

• For all areas in a single component, including all tickets for tests, code, docs, etc.
• For a single area across all components, such as bugs, docs, tests, infra, or even planning itself.

The proposed labels give us that, plus some much-needed labels around planning and processes.