Skip to content

Update Labs Readme #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 9, 2022
Merged

Update Labs Readme #147

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 29 additions & 12 deletions ReadMe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,40 @@

# 🧪 Community Toolkit Labs for Windows 🧪

Welcome to the home of Toolkit Labs experiments for Windows (built on top of WinUI 2, WinUI 3, and [Uno Platform](https://platform.uno)). Find out more about Toolkit Labs in our [Wiki here](https://aka.ms/toolkit/wiki/labs). It includes more about our motivations for having this space as well as how to setup the NuGet feed required to easily use experiments found in this repo.
Welcome to the home of Toolkit Labs experiments for Windows (built on top of WinUI 2, [WinUI 3](https://aka.ms/winui3), and [Uno Platform](https://platform.uno)). Find out more about Toolkit Labs in our [Wiki here](https://aka.ms/toolkit/wiki/labs). It includes more about our motivations for having this space as well as how to setup the NuGet feed required to easily use experiments found in this repo.

This is the starting place for all new features to make it into the [Windows Community Toolkit](https://aka.ms/wct). It is a useful prototyping space as well as a space to work collaboratively on polishing a feature. This allows a final PR into the main Toolkit repo to go as smoothly as possible once a feature is ready to go.

## Sample App
## Getting Started

You can build the main Sample App solution to see all the experiments currently available in this repository. If there's a specific experiment you're interested in, you can navigate to its directory and open up it's individual solution to see samples specific to that feature. You can also read the next section to find out how to grab a pre-built NuGet package for each feature available here.
**[See the list of our current open experiments to try here!](https://github.com/CommunityToolkit/Labs-Windows/issues?q=is%3Aopen+is%3Aissue+label%3A%22experiment+%3Atest_tube%3A%22)**

## Using an Experiment
You can find the corresponding `CommunityToolkit.Labs` packages in our Azure DevOps Feed, [find out more about Preview Packages here](https://aka.ms/toolkit/wiki/previewpackages).

If you skipped the [Wiki page on Toolkit Labs](https://aka.ms/toolkit/wiki/labs), then you can go to the [wiki page on Preview Packages](https://aka.ms/toolkit/wiki/previewpackages) and find out how to add our NuGet Feed to Visual Studio:
> <https://pkgs.dev.azure.com/dotnet/CommunityToolkit/_packaging/CommunityToolkit-Labs/nuget/v3/index.json>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why's this here?
Should it go in the above-linked wiki?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it's there as well, just pulling it out directly to be more visible and a break that would let folks stop while reading and see there's a specific feed.


```
https://pkgs.dev.azure.com/dotnet/CommunityToolkit/_packaging/CommunityToolkit-Labs/nuget/v3/index.json
```
If you find an experiment useful, please up-vote 👍 its corresponding issue and comment with any feedback. Each experiment has an issue assigned to it with the `experiment` label for tracking. Please file any feedback or issues about that experiment on that singular issue. For any other questions or concerns, please open a Discussion (TODO: Link TBD).

If you find an experiment useful, please up-vote 👍 its corresponding issue. Each experiment has an issue assigned to it with the `experiment` label for tracking. Please file any feedback or issues about that experiment on that singular issue. For any other questions or concerns, please open a Discussion.
Otherwise, you can clone the repo, open the `labs` directory, navigate within the folder for a particular experiment and open up it's solution file in Visual Studio. Run one of the project heads (_ExperimentName.Uwp/Wasm/WinAppSDK_) to see its samples.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this also mention using code spaces?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think it's something to call out and explain better. Maybe in the wiki once we have that setup. That's only going to be available to folks that are part of the Toolkit org, so I don't think it's something we need to call out just yet. I'm sure there's more we'll add here in the future. Goal here was just to add a bit more detail to the current setup.


## Build Requirements

- Visual Studio 2022 (UWP & Desktop Workloads for .NET)
- .NET 6 SDK
- Windows App SDK
- Windows SDK 19041

## Adding a new Experiment

To start a new experiment, open up a new Discussion to propose your idea with the community. Be sure to follow the template and highlight reasons why and how your idea can aid other developers.

Once there is traction an issue will be created to track your experiment and its progress.
Once there is traction and your idea is approved, an issue will be created to track your experiment and its progress.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence raises lots of questions:
How is traction defined?
How do ideas get approved?
What if an idea isn't approved?
How is progress tracked?
etc.
I'm not saying answers to these questions need to be in this document, but they need to be somewhere to set appropriate expectations.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we've still got #47 open which is to track more of these details, which we'll put in the wiki. Definitely something we should have documented.


[Create a new experiment from the template](https://github.com/CommunityToolkit/Labs-Windows/tree/main/template).
Then you can fork the Labs repo, create a new branch, and start working on your feature (or porting over your existing prototype).

Then open a PR to start your experiment, not everything needs to be done in your initial PR. The Labs space is a great place to work on something over time, get feedback from the community, and collaborate with others. However, your initial PR should compile and have enough content for folks to understand how to leverage your component.
[Read more about creating a new experiment from the template folder here.](https://github.com/CommunityToolkit/Labs-Windows/tree/main/template)

Then open a PR, not everything needs to be done in your initial PR, but some basically functionality and a usage example should exist. The Labs space is a great place to work on something over time, get feedback from the community, and collaborate with others. However, your initial PR should compile and have enough content for folks to understand how to leverage your component.

## Modifying an Experiment

Expand All @@ -44,3 +51,13 @@ Not all experiments are successful, and that's ok! That's why we experiment!
If there is enough interest in an experiment, it can be time to move it into the main Windows Community Toolkit repo. These experiments should have all the components required implemented like a sample, documentation, and unit tests.

Open up an issue on the main Toolkit repo using the `Toolkit Labs Transfer` Issue Template. (TODO: Link) Use that issue to discuss where in the Toolkit the new component should be placed and what release it should be shipped in. An initial review pass of the code will happen as well. Once the transfer issue is approved, open up a PR to copy over the experiment to its new home.

## Building the Sample App

You can build the main Sample App solution to see all the experiments currently available in this repository by running the `GenerateAllSolution.ps1` PowerShell script in the repo root. Then just open the `Toolkit.Labs.All.sln` solution in Visual Studio. You can run one of the project heads under the platforms folder such as `CommunityToolkit.Labs.WinAppSdk` to run the sample app for that platform.

If you'd like to run a head beyond UWP, Wasm, or the WinAppSDK, you'll need to run the `UseTargetFrameworks.ps1` script first in the `common/Scripts` directory. e.g. `.\UseTargetFrameworks.ps1 -targets all`

If you'd like to test on Uno + Windows App SDK over Uno + UWP, run the `UseUnoWinUI.ps1` script. e.g. `.\UseUnoWinUI.ps1 -targets 3`

If there's a specific experiment you're interested in instead, you can navigate to its directory and open up it's individual solution to see samples specific to that feature. You can also read the next section to find out how to grab a pre-built NuGet package for each feature available here.