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

## 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 https://github.com/CommunityToolkit/Windows/issues/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`](https://github.com/WindowsAppCommunity/meta/issues/1) Practical high-level organization of Areas and Tasks via Labels
- [`WindowsAppCommunity/meta#2`](https://github.com/WindowsAppCommunity/meta/issues/2) Balancing capability and capacity between individual and collective requirements
- [`WindowsAppCommunity/meta#6`](https://github.com/WindowsAppCommunity/meta/issues/6) Introducing the Area-Task Labeling Administration System: ATLAS

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`](https://github.com/WindowsAppCommunity/meta/issues/new) 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.