Document how Labs and WCT Processes work

[michael-hawker]

Overview

This is a tracking/discussion issue around how Toolkit Labs works as part of the ecosystem of the Toolkit.

Basically, this is the lifecycle of a feature going from idea/concept to implementation and into the main Toolkit repository.

Proposed Process

This is my current thinking around how Labs and the Windows Community Toolkit repo work together to allow us better collaboration with our community as well as the ability for us to better manage our releases, features, and structure of maintaining a large project used by so many others.

Every New Feature Starts in Toolkit Labs 🧪

1. Someone (community member, toolkit maintainer, partner, etc...) [aka the experiment 'Champion'] has an idea for something they want to contribute to the Toolkit (or maybe even a prototype already).
2. They should first post a Discussion in a new Thread under 💡 Ideas forum
3. There we can discuss the proposal and if the idea has merit for something we could see a number of folks using the Toolkit.
4. If the proposal is acceptable, an Issue should get created (linked to the discussion). Issues will only track current experiments and have a checklist of criteria which experiments need in order to be considered to be migrated into the main Toolkit repo. E.g. Samples, Docs, Unit Tests, etc...
5. A PR can be opened with an initial experiment (linking to the issue), at minimum it should contain functional code with some demonstration of the code working. It doesn't need to be complete or polished, it can be just a rough-prototype, but should show something that could be 'usable'. It doesn't need full docs or unit tests or anything at this point. Criteria for success and merging is basically that the PR has followed the process above, it builds and does something, and doesn't contain any malicious code (as we would expect).
6. From here, folks can collaborate with the Toolkit team or others in the community to work on improving the feature, getting feedback from others via the NuGet Labs Preview Feed, etc... and work towards checking off the checklist of requirements. Folks can use the open issue to vote on the idea and provide comments or bugs as feedback (or the linked discussion). Votes on the issue will be the main ones tracked for popularity/prioritization of any Toolkit-team assistance.
7. Once the checklist is nearing completion (and also earlier when the initial code is felt to be 'feature complete') a request can be made to do a more thorough review with the Toolkit team. This can point out more architectural concerns or issues we see in the API surface which could be improved upon to help with the generalization or applicability of the component in certain use-cases or to align with existing API conventions, for instance.
8. Once the review has completed and sees no major red-flags, an issue is opened in the main Toolkit repo pointing back to the Experiment. The contributor may still have things to address at this point before final review, but the process to integrate into the main Toolkit will be green-lit at this point.

The other alternative is that an Experiment may not be successful (for whatever reason: technical hurdle, too niche, no interest from community, experiment champion abandons, etc...) and archived/closed.

The Main Toolkit Repo 🧰

The Main Toolkit repo is reserved for tracking releases and work for the upcoming milestone. There are two main areas for feedback used in the Toolkit Repo:

• Discussions will be used for Q&A and announcements/engagements with the community for planning, etc...
• Issues will track bugs or other pieces of concreate/well-defined work that is tracked for the current release (or backlog). They will also be used to track features coming from Labs.

No issues will represent feature requests, those would go into the Toolkit Labs Discussions instead.

PRs that are outside the scope of maintenance and bug-fixes will be closed without a corresponding issue (unless small typo/trivial fixes).

Experiment Migration Process

1. When an Issue is filed in the main repo coming from an approved experiment (w/ link), it is evaluated by the Toolkit team to identify where the feature fits within the current release cycle and can schedule an appropriate integration timeline. Where in the Toolkit (i.e. what package) that feature belongs in will be discussed as well.
2. When given the go ahead, the experiment champion can open a PR on the main repo (linked to the issue in the main repo) migrating their code from the Labs repo into the appropriate place in the Toolkit. Ideally, since we have aligned infrastructure, we should have a script that can help with this part or something.
3. They can then ensure it builds and get information about any other quality gates related to the full CI pipeline, for instance package size.
4. At this point the Champion should have addressed any issues from the thorough review done in Labs.
5. A Final Review is performed as part of the regular PR process (which should be streamlined by earlier reviews). The PR is then merged and the feature will ship in the next version of the Toolkit! 🎉🎉🎉

Open Questions

• When is something a new 'feature' vs. an improvement to an existing API and how do those fit in this process? Where do those get discussed if coming from the community?

[mrlacey]

It'll be good to be clear about the repository within which issues and discussions should be had. I know it's a minor point and they can be moved, it's good to be clear about these things so expectations can be set and met appropriately.

To clarify. Once a Labs PR contains basic functionality it will be merged into main in the Labs repo. Further revision will be done to it there (probably working off forks from main) until it's either ready to move to the main toolkit repo or is abandoned/archived/closed.

[mrlacey]

When is something a new 'feature' vs. an improvement to an existing API and how do those fit in this process? Where do those get discussed if coming from the community?

Is there any historical precedent for this from the toolkit? How was it handled there/then?

[mrlacey]

One thing that will be a really useful reference (both to help set up Labs but also in its early life) would be to take something that was recently added to the main toolkit and extract that back to Labs.
This would:

• Provide a "real" and complete example.
• Show everything that might be needed in a Labs experiment before being promoted.
• Show how/where the things in a Labs experiment move to when they get promoted to the main toolkit.

It doesn't need a full (artificial) development history and can take what's in the Toolkit now.

[michael-hawker]

When is something a new 'feature' vs. an improvement to an existing API and how do those fit in this process? Where do those get discussed if coming from the community?

Is there any historical precedent for this from the toolkit? How was it handled there/then?

Since everything minor and major has just been done as PRs in the main repo before, there's not a lot of precedent. Though it was still just a large PR at worst.

I think we have a few options?

1. Copy code into Labs in order to refactor/improve and try out things, collaborate, test, etc... in an easier environment.
2. Since we have labs infrastructure in root hopefully, we could fork and just do more work there before opening a PR.
3. We could leverage more feature type branches for these things?

One thing that will be a really useful reference (both to help set up Labs but also in its early life) would be to take something that was recently added to the main toolkit and extract that back to Labs. This would:

For sure, I was thinking the new GridSplitter refactor may be on this list of candidates. I'm also not too worried about having a variety of experiments in flight by the time we go public in varying states of development too.

[michael-hawker]

See initial drafts/proposals for templates/process work in the GridSplitter experiment in #96 (discussion) and #101 (tracking issue).