Reorganize developer documentation (#2576)

microsoft · Apr 11, 2024 · 8bdafc8 · 8bdafc8
1 parent 7101fa6
commit 8bdafc8
Show file tree

Hide file tree

Showing 34 changed files with 183 additions and 223 deletions.
diff --git 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 <kbd>F5</kbd>. 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
@@ -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 <kbd>F5</kbd>. 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
@@ -49,25 +49,25 @@ 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
 
 The tools are a set of functionalities that are integrated within Dev Home's codebase. They are designed to provide specific capabilities or features to Dev Home. They live as their own component but run in the same process as Dev Home and can communicate with each other and the core component through Dev Home's API.
 
 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/...environments/Interfaces/IComputeSystem.md → ...environments/Interfaces/IComputeSystem.md b/...environments/Interfaces/IComputeSystem.md → ...environments/Interfaces/IComputeSystem.md
diff --git a/...ents/Interfaces/IComputeSystemProvider.md → ...ents/Interfaces/IComputeSystemProvider.md b/...ents/Interfaces/IComputeSystemProvider.md → ...ents/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 → docs/extensions/environments/readme.md b/docs/environments/Environments-General.md → docs/extensions/environments/readme.md
diff --git a/docs/extensions.md → docs/extensions/readme.md b/docs/extensions.md → 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
@@ -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. Create a [Draft Pull Request (PR)](https://github.blog/2019-02-14-introducing-draft-pull-requests/)-->
-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.
-<!--
-## GitHub Workflow
-
-- Before starting to work on a fix/feature, make sure there is an open issue to track the work.
-- Add the `In progress` label to the issue, if not already present also add a `Cost-Small/Medium/Large` estimate and make sure all appropriate labels are set.
-- If you are a community contributor, you will not be able to add labels to the issue, in that case just add a comment saying that you started to work on the issue and try to give an estimate for the delivery date.
-- If the work item has a medium/large cost, using the markdown task list, list each sub item and update the list with a check mark after completing each sub item.
-- When opening a PR, follow the PR template.
-- 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.
-- When the PR is approved, let the owner of the PR merge it. For community contributions the reviewer that approved the PR can also merge it.
-- Use the `Squash and merge` option to merge a PR, if you don't want to squash it because there are logically different commits, use `Rebase and merge`.
-- We don't close issues automatically when referenced in a PR, so after the PR is merged:
-  - mark the issue(s), that the PR solved, with the `Resolution-Fix-Committed` label, remove the `In progress` label and if the issue is assigned to a project, move the item to the `Done` status.
-  - don't close the issue if it's a bug in the current released version since users tend to not search for closed issues, we will close the resolved issues when a new version is released.
-  - if it's not a code fix that affects the end user, the issue can be closed (for example a fix in the build or a code refactoring and so on).
--->
-## 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
@@ -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
@@ -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
@@ -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
@@ -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.