From 8bdafc8a69eeec45886103e8a9142b6e1e5602eb Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Thu, 11 Apr 2024 10:40:48 -0400 Subject: [PATCH] Reorganize developer documentation (#2576) --- CONTRIBUTING.md | 30 +++++++ README.md | 15 ---- docs/architecture.md | 14 ++-- .../environments/Interfaces/IComputeSystem.md | 0 .../Interfaces/IComputeSystemProvider.md | 2 +- .../environments/readme.md} | 0 docs/{extensions.md => extensions/readme.md} | 10 +-- docs/readme.md | 63 +-------------- docs/roadmap.md | 40 ++++++---- .../Templates/Introduction/C#/README.md | 4 +- .../Introduction/C#/configuration.dsc.yaml | 2 +- .../Templates/Introduction/C++/README.md | 4 +- .../Introduction/C++/configuration.dsc.yaml | 2 +- .../Introduction/JavaScript.NodeJS/README.md | 2 +- .../JavaScript.NodeJS/configuration.dsc.yaml | 2 +- .../Introduction/PowerShell/README.md | 2 +- .../Introduction/Python3.12/README.md | 4 +- .../Python3.12/configuration.dsc.yaml | 2 +- .../Templates/Introduction/README.md | 2 +- docs/tools.md | 79 ------------------- docs/{ => tools}/ExperimentalFeatures.md | 0 docs/tools/advanced-tool-behavior.md | 24 ++++++ docs/{ => tools}/common/CloseButton.md | 0 docs/{ => tools}/common/Readme.md | 6 +- docs/{ => tools}/common/SecondaryWindow.md | 0 docs/{ => tools}/common/StringResource.md | 0 .../common/WindowOpenFileDialog.md | 0 .../common/WindowOpenFolderDialog.md | 0 .../common/WindowSaveFileDialog.md | 0 docs/{ => tools}/common/WindowTitleBar.md | 0 docs/tools/creating-a-tool.md | 59 ++++++++++++++ docs/{ => tools}/navconfig.md | 2 +- docs/tools/readme.md | 9 +++ src/README.md | 27 ------- 34 files changed, 183 insertions(+), 223 deletions(-) rename docs/{ => extensions}/environments/Interfaces/IComputeSystem.md (100%) rename docs/{ => extensions}/environments/Interfaces/IComputeSystemProvider.md (99%) rename docs/{environments/Environments-General.md => extensions/environments/readme.md} (100%) rename docs/{extensions.md => extensions/readme.md} (89%) delete mode 100644 docs/tools.md rename docs/{ => tools}/ExperimentalFeatures.md (100%) create mode 100644 docs/tools/advanced-tool-behavior.md rename docs/{ => tools}/common/CloseButton.md (100%) rename docs/{ => tools}/common/Readme.md (89%) rename docs/{ => tools}/common/SecondaryWindow.md (100%) rename docs/{ => tools}/common/StringResource.md (100%) rename docs/{ => tools}/common/WindowOpenFileDialog.md (100%) rename docs/{ => tools}/common/WindowOpenFolderDialog.md (100%) rename docs/{ => tools}/common/WindowSaveFileDialog.md (100%) rename docs/{ => tools}/common/WindowTitleBar.md (100%) create mode 100644 docs/tools/creating-a-tool.md rename docs/{ => tools}/navconfig.md (97%) create mode 100644 docs/tools/readme.md delete mode 100644 src/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26526cba71..bf20277fb7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -153,6 +153,36 @@ Once you've discussed your proposed feature/fix/etc. with a team member and you' 5. Work on your changes 6. Build and see if it works +## Building the code + +1. Clone the repository +2. Configure your system + * Please use the [configuration file](.configurations/configuration.dsc.yaml). This can be applied by either: + * Dev Home's machine configuration tool + * WinGet configuration. If you have WinGet version [v1.6.2631 or later](https://github.com/microsoft/winget-cli/releases), run `winget configure .configurations/configuration.dsc.yaml` in an elevated shell from the project root so relative paths resolve correctly + * Alternatively, if you already are running the minimum OS version, have Visual Studio installed, and have developer mode enabled, you may configure your Visual Studio directly via the .vsconfig file. To do this: + * Open the Visual Studio Installer, select “More” on your product card and then "Import configuration" + * Specify the .vsconfig file at the root of the repo and select “Review Details” + +## Running & debugging + +In Visual Studio, you should be able to build and debug Dev Home by hitting F5. Make sure to select either the `x64` or the `x86` platform and set DevHome as the selected startup project. + +Alternatively, + +- Open the Developer Command Prompt for Visual Studio +- Run `Build` from Dev Home's root directory. You can pass in a list of platforms/configurations +- The Dev Home MSIX will be in your repo under `AppxPackages\x64\debug` + + +### Rules + +- **Follow the pattern of what you already see in the code.** +- [Coding style](style.md). +- Try to package new ideas/components into libraries that have nicely defined interfaces. +- Package new ideas into classes or refactor existing ideas into a class as you extend. +- When adding new classes/methods/changing existing code: add new unit tests or update the existing tests. + ### Code review When you'd like the team to take a look (even if the work is not yet fully-complete), mark the PR as 'Ready For Review' so that the team can review your work and provide comments, suggestions, and request changes. It may take several cycles but the end result will be solid, testable, conformant code that is safe for us to merge. diff --git a/README.md b/README.md index 863a9df9b7..aff1d488af 100644 --- a/README.md +++ b/README.md @@ -94,21 +94,6 @@ If you would like to ask a question that you feel doesn't warrant an issue (yet) * You must be running Windows 11 21H2 (build >= 10.0.22000.0) to run Dev Home * You must [enable Developer Mode in the Windows Settings app](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development) -## Building the code - -1. Clone the repository -2. Configure your system - * Please use the [configuration file](.configurations/configuration.dsc.yaml). This can be applied by either: - * Dev Home's machine configuration tool - * WinGet configuration. If you have WinGet version [v1.6.2631 or later](https://github.com/microsoft/winget-cli/releases), run `winget configure .configurations/configuration.dsc.yaml` in an elevated shell from the project root so relative paths resolve correctly - * Alternatively, if you already are running the minimum OS version, have Visual Studio installed, and have developer mode enabled, you may configure your Visual Studio directly via the .vsconfig file. To do this: - * Open the Visual Studio Installer, select “More” on your product card and then "Import configuration" - * Specify the .vsconfig file at the root of the repo and select “Review Details” - -## Running & debugging - -In Visual Studio, you should be able to build and debug Dev Home by hitting F5. Make sure to select either the `x64` or the `x86` platform and set DevHome as the selected startup project. - --- ## Code of conduct diff --git a/docs/architecture.md b/docs/architecture.md index 4e7b27fd8f..7fb47116df 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -49,11 +49,11 @@ Dev Home Core is the central part of Dev Home where all the components come toge The Dev Home Common component contains code that is shared among the tools, core, and settings components. It also imports libraries that are used across Dev Home. One such library is the **Dev Home Extension SDK** used to get references to out-of-process extensions. -Dev Home Common also provides logging and telemetry functionality. +Dev Home Common also provides telemetry functionality. ## Settings -This is a special component that acts similarly a tool but isn't actually a tool. The Settings component, like other tools, consumes the Common project and is used by Dev Home Core. It manages user preferences across all tools and extensions. +This is a special component that acts similarly to a tool but isn't actually a tool. The Settings component, like other tools, consumes the Common project and is used by Dev Home Core. It manages user preferences across all tools and extensions. ## Tools @@ -61,13 +61,13 @@ The tools are a set of functionalities that are integrated within Dev Home's cod These tools can use the APIs in the extension SDK to get data or functionality from the extensions. -Learn more about [writing a tool](./tools.md). +Learn more about [tools](./tools/readme.md). Dev Home currently has the following tools: -- [Dashboard](./tools.md#dashboard-tool) -- [Setup flow](./tools.md#setup-flow-tool) -- Extensions +- [Dashboard](./tools/Dashboard.md) +- Setup flow +- Extensions Library - [Windows customization](../tools/Customization/DevHome.Customization/Customization.md) ## Extensions @@ -76,4 +76,4 @@ Extensions are separate packages living as out-of-process components that provid Extensions can be developed by third-party developers or by Dev Home's core development team. These extensions allow Dev Home to be extended without modifying its core codebase. -Learn more about [writing an extension](./extensions.md). +Learn more about [writing an extension](./extensions/readme.md). diff --git a/docs/environments/Interfaces/IComputeSystem.md b/docs/extensions/environments/Interfaces/IComputeSystem.md similarity index 100% rename from docs/environments/Interfaces/IComputeSystem.md rename to docs/extensions/environments/Interfaces/IComputeSystem.md diff --git a/docs/environments/Interfaces/IComputeSystemProvider.md b/docs/extensions/environments/Interfaces/IComputeSystemProvider.md similarity index 99% rename from docs/environments/Interfaces/IComputeSystemProvider.md rename to docs/extensions/environments/Interfaces/IComputeSystemProvider.md index ce2ca6a0d1..35decc5ef9 100644 --- a/docs/environments/Interfaces/IComputeSystemProvider.md +++ b/docs/extensions/environments/Interfaces/IComputeSystemProvider.md @@ -4,7 +4,7 @@ A **compute system provider** is the provider type that Dev Home will query when 1. Retrieve a list of `IComputeSystem`s 2. Create a new compute system -3. Provide Dev Home with an [Adaptive card](https://learn.microsoft.com/en-us/adaptive-cards/) for the creation of a new compute system +3. Provide Dev Home with an [Adaptive card](https://learn.microsoft.com/adaptive-cards/) for the creation of a new compute system 4. Provide Dev Home with an Adaptive card for the modification of a compute systems properties Dev Home will look at the [ComputeSystemProviderOperations](https://github.com/microsoft/devhome/blob/3dc0dd739b0175357cc3e74c713d305c09248537/extensionsdk/Microsoft.Windows.DevHome.SDK/Microsoft.Windows.DevHome.SDK.idl#L461) enum to determine what operations the provider supports. diff --git a/docs/environments/Environments-General.md b/docs/extensions/environments/readme.md similarity index 100% rename from docs/environments/Environments-General.md rename to docs/extensions/environments/readme.md diff --git a/docs/extensions.md b/docs/extensions/readme.md similarity index 89% rename from docs/extensions.md rename to docs/extensions/readme.md index 8056407375..a65f70bfb1 100644 --- a/docs/extensions.md +++ b/docs/extensions/readme.md @@ -1,8 +1,8 @@ # Extensions -Dev Home is an app extension host which uses [out-of-process COM](https://learn.microsoft.com/en-us/samples/dotnet/samples/out-of-process-com-server/) to talk to external COM Server processes that declare themselves to be extensions of Dev Home. +Dev Home is an app extension host which uses [out-of-process COM](https://learn.microsoft.com/samples/dotnet/samples/out-of-process-com-server/) to talk to external COM Server processes that declare themselves to be extensions of Dev Home. -Dev Home currently supports extending two interfaces through the Extension SDK. In addition, extensions can provide widgets to Dev Home using [Widget providers](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/widget-providers). +Dev Home currently supports extending two interfaces through the Extension SDK. In addition, extensions can provide widgets to Dev Home using [Widget providers](https://learn.microsoft.com/windows/apps/develop/widgets/widget-providers). ## Extension basics @@ -13,9 +13,9 @@ An extension can provide functionality for one or more extensibility points. Cur - Developer IDs: Allow developers to sign in and out of a service by implementing the [`IDeveloperIdProvider`](#ideveloperidprovider) interface. - Repositories: Allow developers to get available repositories associated with their Developer IDs or parse repositories from URLs and clone them by implementing the [`IRepositoryProvider`](#irepositoryprovider) interface. -Read more about [Provider interfaces](#provider-interfaces) below. Each extension also must have a class that implements `IExtension`. DevHome needs to create an instance of this class. The GUID of this class must be reflected in the manifest. See [Sample Extension](../SampleExtension/SampleExtension.cs) +Read more about [Provider interfaces](#provider-interfaces) below. Each extension also must have a class that implements `IExtension`. DevHome needs to create an instance of this class. The GUID of this class must be reflected in the manifest. See [Sample Extension](../../extensions/SampleExtension/SampleExtension.cs) -![Extension Flow](./images/extension-flow.png) +![Extension Flow](../images/extension-flow.png) ## Extension manifest @@ -120,7 +120,7 @@ public interface IRepository ## Sequence diagram -![Extension Sequence](./images/extension-sequence.png) +![Extension Sequence](../images/extension-sequence.png) ## Runtime logic diff --git a/docs/readme.md b/docs/readme.md index fe9db5461b..31bd0c698f 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,62 +1,7 @@ # Dev Documentation -## Fork, Clone, Branch and Create your PR - -Once you've discussed your proposed feature/fix/etc. with a team member, and you've agreed on an approach or a spec has been written and approved, it's time to start development: - -1. Fork the repo if you haven't already -1. Clone your fork locally -1. Create & push a feature branch -1. Work on your changes - -## Rules - -- **Follow the pattern of what you already see in the code.** -- [Coding style](style.md). -- Try to package new ideas/components into libraries that have nicely defined interfaces. -- Package new ideas into classes or refactor existing ideas into a class as you extend. -- When adding new classes/methods/changing existing code: add new unit tests or update the existing tests. - -## Compiling Dev Home - -### Compiling Source Code - -There are two ways to compile locally. - -- Open the Developer Command Prompt for Visual Studio -- Run `Build` from Dev Home's root directory. You can pass in a list of platforms/configurations -- The Dev Home MSIX will be in your repo under `AppxPackages\x64\debug` - -Alternatively - -- Open `DevHome.sln` in Visual Studio, in the `Solutions Configuration` drop-down menu select `Release` or `Debug`, from the `Build` menu choose `Build Solution`. - -### Dev Home framework - -The Dev Home project contains the wrapping framework for Dev Home. -It's responsible for: -- Loading the individual Dev Home tools. -- Loading out-of-process extensions. -- Loading the main window and creating a skeleton UI. - - -## More - +Before you dive into developing for Dev Home, check out these resources: - [Dev Home Architecture](./architecture.md) -- [Dev Home Tools](./tools.md) -- [Dev Home Extensions](./extensions.md) +- [Dev Home Tools](./tools/readme.md) +- [Dev Home Extensions](./extensions/extensions.md) + diff --git a/docs/roadmap.md b/docs/roadmap.md index 475c3ea72c..ba9b7c1009 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -30,21 +30,24 @@ Last, but certainly not least are features and bugs with the most 👍 indicatin ## Release cadence -Dev Home is engineered and delivered as a set of 4-week [milestones]. Below is the schedule for when milestones will be included in release builds of Dev Home. The dates are rough estimates and are subject to change. - -| Milestone end date | Milestone name | Blog post | -| ------------------ | -------------- | --------- | -| 2023-05-23 | 0.1 | [Introducing Dev Home] | -| 2023-06-15 | [0.2] | [Dev Home Preview 0.2 Release] | -| 2023-07-13 | [0.3] | [Dev Home Preview 0.3 Release] | -| 2023-08-17 | [0.4] | [Dev Home Preview 0.4 Release] | -| 2023-09-14 | [0.5] | | -| 2023-10-12 | [0.6] | | -| 2023-11-16 | [0.7] | | -| 2023-12-14 | 0.8 | | -| 2024-01-18 | 0.9 | | -| 2024-02-15 | 0.10 | | -| 2024-03-14 | 0.11 | | +Dev Home is engineered and delivered as a set of monthly [milestones]. Below is the schedule for when milestones will be included in release builds of Dev Home. The dates are rough estimates and are subject to change. + +| Milestone end date | Milestone name | Blog post | +| ------------------- | -------------- | --------- | +| 2023-05-23 | 0.1 | [Introducing Dev Home] | +| 2023-06-15 | [0.2] | [Dev Home Preview 0.2 Release] | +| 2023-07-13 | [0.3] | [Dev Home Preview 0.3 Release] | +| 2023-08-17 | [0.4] | [Dev Home Preview 0.4 Release] | +| 2023-09-19 | [0.5] | | +| 2023-10-17 | [0.6] | | +| 2023-11-14 | [0.7] | | +| 2023-12-12 | [0.8] | | +| 2024-01-08 | [0.9] | | +| 2024-01-16 | [0.10] | | +| 2024-02-21 | [0.11] | | +| 2024-03-12 | [0.12] | | +| 2024-04-16 | [0.13] | | +| 2024-05-14 | [0.14] | | [Features]: https://github.com/microsoft/devhome/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3AIssue-Feature+ [Bugs]: https://github.com/microsoft/devhome/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3AIssue-Bug+ @@ -56,6 +59,13 @@ Dev Home is engineered and delivered as a set of 4-week [milestones]. Below is t [0.5]: https://github.com/microsoft/devhome/milestone/5 [0.6]: https://github.com/microsoft/devhome/milestone/9 [0.7]: https://github.com/microsoft/devhome/milestone/10 +[0.8]: https://github.com/microsoft/devhome/milestone/11 +[0.9]: https://github.com/microsoft/devhome/milestone/12 +[0.10]: https://github.com/microsoft/devhome/milestone/13 +[0.11]: https://github.com/microsoft/devhome/milestone/14 +[0.12]: https://github.com/microsoft/devhome/milestone/15 +[0.13]: https://github.com/microsoft/devhome/milestone/16 +[0.14]: https://github.com/microsoft/devhome/milestone/17 [Introducing Dev Home]: https://blogs.windows.com/windowsdeveloper/2023/05/30/introducing-dev-home/ [Dev Home Preview 0.2 Release]: https://blogs.windows.com/windowsdeveloper/2023/06/21/dev-home-preview-0-2-release/ diff --git a/docs/sampleConfigurations/Templates/Introduction/C#/README.md b/docs/sampleConfigurations/Templates/Introduction/C#/README.md index 11f9ed7a30..e63e6c902c 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C#/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/C#/README.md @@ -1,12 +1,12 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Community 2022 * Required Visual Studio Workloads (ManagedDesktop, Universal) * GitHub Desktop -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File The following two options are available for running a WinGet Configuration file on your device. diff --git a/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml index 00094e3d28..2f2e74114c 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with C# development on Windows # -# Reference: https://learn.microsoft.com/en-us/visualstudio/get-started/csharp/tutorial-console # +# Reference: https://learn.microsoft.com/visualstudio/get-started/csharp/tutorial-console # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/C++/README.md b/docs/sampleConfigurations/Templates/Introduction/C++/README.md index f65a4a8da4..a643d69e1b 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C++/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/C++/README.md @@ -1,12 +1,12 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Community 2022 * Required Visual Studio Workloads (NativeDesktop, Universal) * GitHub Desktop -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File The following two options are available for running a WinGet Configuration file on your device. diff --git a/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml index f22a0ae98f..62943701e9 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with C++ development on Windows # -# Reference: https://learn.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170 # +# Reference: https://learn.microsoft.com/cpp/build/vscpp-step-0-installation?view=msvc-170 # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md index 6e9d897571..cc0dea182d 100644 --- a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md @@ -7,7 +7,7 @@ When run, the `configuration.dsc.yaml` file will install the following list of a * GitHub Desktop -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File diff --git a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml index c58bb2f066..660d9b8ec4 100644 --- a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with NodeJS development on Windows # -# Reference: https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows # +# Reference: https://learn.microsoft.com/windows/dev-environment/javascript/nodejs-on-windows # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md b/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md index baa22881a9..522711c667 100644 --- a/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md @@ -1,5 +1,5 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Code diff --git a/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md b/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md index 361b2ea0d9..df711a8bd6 100644 --- a/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md @@ -1,5 +1,5 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Community 2022 @@ -7,7 +7,7 @@ When run, the `configuration.dsc.yaml` file will install the following list of a * GitHub Desktop * Python 3.12 -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File The following two options are available for running a WinGet Configuration file on your device. diff --git a/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml index a24bfc53f8..3d9dbf1d31 100644 --- a/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with Python development on Windows # -# Reference: https://learn.microsoft.com/en-us/windows/python/beginners # +# Reference: https://learn.microsoft.com/windows/python/beginners # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/README.md b/docs/sampleConfigurations/Templates/Introduction/README.md index c7b7cff19b..f7b364226b 100644 --- a/docs/sampleConfigurations/Templates/Introduction/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/README.md @@ -1,4 +1,4 @@ -This directory contains different [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration files](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) that will be used for setting up your device for a specific software development language. These files are designed specifically for providing an introduction to software development, creating the default *Hello World* project, without having to focus on understanding the complexities of what needs to be installed, and how should it be configured. +This directory contains different [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration files](https://learn.microsoft.com/windows/package-manager/configuration/) that will be used for setting up your device for a specific software development language. These files are designed specifically for providing an introduction to software development, creating the default *Hello World* project, without having to focus on understanding the complexities of what needs to be installed, and how should it be configured. ## Language specific folders (Naming Standard) Each folder in this folder will be labeled with the name of the Software Development language it is associated with. If the language is inclusive of another language, it'll be seperated by a decimal. If the language contains a version specific release that needs to be accounted for, then the version will be considered as the language. diff --git a/docs/tools.md b/docs/tools.md deleted file mode 100644 index 5a76119de2..0000000000 --- a/docs/tools.md +++ /dev/null @@ -1,79 +0,0 @@ -# Tools - -Dev Home adds functionality through a set of tools. Each tool provides a page in the Dev Home navigation view. Currently, all tools come from in-package assemblies. Third party or out-of-process tools are not supported at this time. - -Tools utilize data and functionality from out-of-process [extensions](./extensions.md). This is done through the Extension SDK API. - -## Writing a Tool - -1. Create a new directory with your tool's name under `tools` with three subdirectories `src`, `test`, and `uitest` -1. Create a new `WinUI 3 Class Library` project in your `src` directory -1. Create the `Strings\en-us` directories under `src`. Add `Resources.resw` and include the following code: - ```xml - - [Name of your tool that will appear in navigation menu] - [Extra information about the name of your tool that may help translation] - - ``` -1. Add a project reference from `DevHome` to your project -1. Add a project reference from your project to `DevHome.Common.csproj` project under [/common/](/common) -1. Create your XAML View and ViewModel. Your View class must inherit from `ToolPage` and implement [tool interface requirements](#tool-requirements). -1. Update [NavConfig.jsonc](/src/NavConfig.jsonc) with your tool. Specifications for the [NavConfig.json schema](navconfig.md). - -### Tool requirements - -Each tool must define a custom page view extending from the [`ToolPage`](../common/ToolPage.cs) abstract class, and implement it like in this example: - -```cs -public class SampleToolPage : ToolPage -{ - public override string ShortName => "SampleTool"; - - public SampleToolPage() - { - ViewModel = Application.Current.GetService(); - InitializeComponent(); - } -} -``` - -The Dev Home framework will look at all types in its assembly for any inheriting from `ToolPage`: - -On a found type, the framework will use: - - ShortName property to get the name of the tool - -#### Method definition - -This section contains a more detailed description of each of the interface methods. - -ShortName - -```cs -public abstract string ShortName { get; } -``` - -Returns the name of the tool. This is used for the navigation menu text. - -### Code organization - -[`toolpage.cs`](../common/ToolPage.cs) -Contains the interface definition for Dev Home tools. - -### Navigation - -In order to allow navigation to your tool, your page and ViewModel must be registered with the PageService. If your tool only contains one page, it is automatically registered for you since you added your page to `NavConfig.jsonc`. However, you may have other sub-pages you wish to register. - -In order to do so, you must create an extension method for the PageService inside your tool. See examples in [Settings](../settings/DevHome.Settings/Extensions/PageExtensions.cs) or [Extensions](../tools/ExtensionLibrary/DevHome.ExtensionLibrary/Extensions/PageExtensions.cs). Then, call your extension from the [PageService](../src/Services/PageService.cs). - -#### Navigating away from your tool - -If you want a user action (such as clicking a link) to navigate away from your tool and your project does not otherwise rely on the destination project, do not create a PackageReference to the destination project from yours. Instead, add the destination page to `INavigationService.KnownPageKeys` and use it for navigation, like in this example: -```cs -navigationService.NavigateTo(KnownPageKeys.); -``` - -This keeps the dependency tree simple, and prevents circular references when two projects want to navigate to each other. - -## Existing tools - -[Dashboard](./tools/Dashboard.md) diff --git a/docs/ExperimentalFeatures.md b/docs/tools/ExperimentalFeatures.md similarity index 100% rename from docs/ExperimentalFeatures.md rename to docs/tools/ExperimentalFeatures.md diff --git a/docs/tools/advanced-tool-behavior.md b/docs/tools/advanced-tool-behavior.md new file mode 100644 index 0000000000..fc653ff186 --- /dev/null +++ b/docs/tools/advanced-tool-behavior.md @@ -0,0 +1,24 @@ +# Advanced Tool behavior + +## Headers + +Coming soon. + +## Navigation + +In order to allow navigation to your tool, your page and ViewModel must be registered with the PageService. If your tool only contains one page, it is automatically registered for you since you added your page to `NavConfig.jsonc`. However, you may have other sub-pages you wish to register. + +In order to do so, you must create an extension method for the PageService inside your tool. See examples in [Settings](../settings/DevHome.Settings/Extensions/PageExtensions.cs) or [Extensions](../tools/ExtensionLibrary/DevHome.ExtensionLibrary/Extensions/PageExtensions.cs). Then, call your extension from the [PageService](../src/Services/PageService.cs). + +### Navigating away from your tool + +If you want a user action (such as clicking a link) to navigate away from your tool and your project does not otherwise rely on the destination project, do not create a PackageReference to the destination project from yours. Instead, add the destination page to `INavigationService.KnownPageKeys` and use it for navigation, like in this example: +```cs +navigationService.NavigateTo(KnownPageKeys.); +``` + +This keeps the dependency tree simple, and prevents circular references when two projects want to navigate to each other. + +## Common controls + +Dev Home has a set of common controls that are generic, customizable and reusable from all pages and tools in Dev Home. See [Common controls](./common/Readme.md). \ No newline at end of file diff --git a/docs/common/CloseButton.md b/docs/tools/common/CloseButton.md similarity index 100% rename from docs/common/CloseButton.md rename to docs/tools/common/CloseButton.md diff --git a/docs/common/Readme.md b/docs/tools/common/Readme.md similarity index 89% rename from docs/common/Readme.md rename to docs/tools/common/Readme.md index af87ea4a2f..bfca75325c 100644 --- a/docs/common/Readme.md +++ b/docs/tools/common/Readme.md @@ -17,4 +17,8 @@ List of common controls that are generic, customizable and reusable from all pag - [WindowOpenFileDialog](./WindowOpenFileDialog.md) - [WindowOpenFolderDialog](./WindowOpenFolderDialog.md) -- [WindowSaveFileDialog](./WindowSaveFileDialog.md) \ No newline at end of file +- [WindowSaveFileDialog](./WindowSaveFileDialog.md) + +## Custom Adaptive Card schema + +Coming soon. diff --git a/docs/common/SecondaryWindow.md b/docs/tools/common/SecondaryWindow.md similarity index 100% rename from docs/common/SecondaryWindow.md rename to docs/tools/common/SecondaryWindow.md diff --git a/docs/common/StringResource.md b/docs/tools/common/StringResource.md similarity index 100% rename from docs/common/StringResource.md rename to docs/tools/common/StringResource.md diff --git a/docs/common/WindowOpenFileDialog.md b/docs/tools/common/WindowOpenFileDialog.md similarity index 100% rename from docs/common/WindowOpenFileDialog.md rename to docs/tools/common/WindowOpenFileDialog.md diff --git a/docs/common/WindowOpenFolderDialog.md b/docs/tools/common/WindowOpenFolderDialog.md similarity index 100% rename from docs/common/WindowOpenFolderDialog.md rename to docs/tools/common/WindowOpenFolderDialog.md diff --git a/docs/common/WindowSaveFileDialog.md b/docs/tools/common/WindowSaveFileDialog.md similarity index 100% rename from docs/common/WindowSaveFileDialog.md rename to docs/tools/common/WindowSaveFileDialog.md diff --git a/docs/common/WindowTitleBar.md b/docs/tools/common/WindowTitleBar.md similarity index 100% rename from docs/common/WindowTitleBar.md rename to docs/tools/common/WindowTitleBar.md diff --git a/docs/tools/creating-a-tool.md b/docs/tools/creating-a-tool.md new file mode 100644 index 0000000000..a8be7e740b --- /dev/null +++ b/docs/tools/creating-a-tool.md @@ -0,0 +1,59 @@ +# Creating a tool + +1. Create a new directory with your tool's name under `tools` with three subdirectories `src`, `test`, and `uitest` +1. Create a new `WinUI 3 Class Library` project in your `src` directory +1. In your project file, remove `TargetFramework` and `TargetPlatformMinVersion`. Add the following line to the top: + ```xml + + ``` +1. Remove the PackageReference to WindowsAppSDK, since it will be added via the Common project in a few steps. +1. Create the `Strings\en-us` directories under `src`. Add `Resources.resw` and include the following code: + ```xml + + [Name of your tool that will appear in navigation menu] + [Extra information about the name of your tool that may help translation] + + ``` +1. Add a project reference from `DevHome.csproj` to your project +1. Add a project reference from your project to `DevHome.Common.csproj` project under [/common/](/common) +1. Create your XAML View and ViewModel. Your View class must inherit from `ToolPage` and implement [tool interface requirements](#tool-requirements). +1. Update [NavConfig.jsonc](/src/NavConfig.jsonc) with your tool. Specifications for the [NavConfig.json schema](./navconfig.md). + +## Tool requirements + +Each tool must define a custom page view extending from the [`ToolPage`](../common/ToolPage.cs) abstract class, and implement it like in this example: + +```cs +public class SampleToolPage : ToolPage +{ + public override string ShortName => "SampleTool"; + + public SampleToolPage() + { + ViewModel = Application.Current.GetService(); + InitializeComponent(); + } +} +``` + +The Dev Home framework will look at all types in its assembly for any inheriting from `ToolPage`: + +On a found type, the framework will use: + - ShortName property to get the name of the tool + +### Method definition + +This section contains a more detailed description of each of the interface methods. + +ShortName + +```cs +public abstract string ShortName { get; } +``` + +Returns the name of the tool. This is used for the navigation menu text. + +## Code organization + +[`toolpage.cs`](../common/ToolPage.cs) +Contains the interface definition for Dev Home tools. \ No newline at end of file diff --git a/docs/navconfig.md b/docs/tools/navconfig.md similarity index 97% rename from docs/navconfig.md rename to docs/tools/navconfig.md index 8f1efc001c..831e115aee 100644 --- a/docs/navconfig.md +++ b/docs/tools/navconfig.md @@ -6,7 +6,7 @@ - path: #/navMenu - **_Properties_** - groups `required` - - Future: Items in navigation menu can be put into expand/collapsable groupings + - Future: Items in navigation menu can be put into expand/collapsible groupings - This is not yet supported and all tools are placed in top-level list - Type: `array` - path: #/navMenu/groups diff --git a/docs/tools/readme.md b/docs/tools/readme.md new file mode 100644 index 0000000000..eaa038ac69 --- /dev/null +++ b/docs/tools/readme.md @@ -0,0 +1,9 @@ +# Tools + +Dev Home adds functionality through a set of tools. Each tool provides a page in the Dev Home navigation view. Currently, all tools come from in-package assemblies. Third party or out-of-process tools are not supported at this time. + +Learn more about [creating a tool](./creating-a-tool.md). Then, learn about [advanced tool behavior](./advanced-tool-behavior.md). + +Tools utilize data and functionality from out-of-process [extensions](../extensions/extensions.md). This is done through the Extension SDK API. + +Tools support [experimental features](./ExperimentalFeatures.md). \ No newline at end of file diff --git a/src/README.md b/src/README.md deleted file mode 100644 index 723a8306c5..0000000000 --- a/src/README.md +++ /dev/null @@ -1,27 +0,0 @@ -*Recommended Markdown Viewer: [Markdown Editor](https://marketplace.visualstudio.com/items?itemName=MadsKristensen.MarkdownEditor2)* - -## Getting Started - -Browse and address `TODO:` comments in `View -> Task List` to learn the codebase and understand next steps for turning the generated code into production code. - -Explore the [WinUI Gallery](https://www.microsoft.com/store/productId/9P3JFPWWDZRC) to learn about available controls and design patterns. - -Relaunch Template Studio to modify the project by right-clicking on the project in `View -> Solution Explorer` then selecting `Add -> New Item (Template Studio)`. - -## Publishing - -For projects with MSIX packaging, right-click on the application project and select `Package and Publish -> Create App Packages...` to create an MSIX package. - -For projects without MSIX packaging, follow the [deployment guide](https://docs.microsoft.com/windows/apps/windows-app-sdk/deploy-unpackaged-apps) or add the `Self-Contained` Feature to enable xcopy deployment. - -## CI Pipelines - -See [README.md](https://github.com/microsoft/TemplateStudio/blob/main/docs/WinUI/pipelines/README.md) for guidance on building and testing projects in CI pipelines. - -## Changelog - -See [releases](https://github.com/microsoft/TemplateStudio/releases) and [milestones](https://github.com/microsoft/TemplateStudio/milestones). - -## Feedback - -Bugs and feature requests should be filed at https://aka.ms/templatestudio.