Add API spec template and handling instructions (#84)

* Fix emdash in readme * API spec template * Update specs/README.md PR feedback Co-authored-by: Jevan Saks <[email protected]> * PR feedback * PR feedback * PR feedback Co-authored-by: Jevan Saks <[email protected]>
microsoft · Jun 22, 2020 · f5a93c3 · f5a93c3
1 parent ee9648e
commit f5a93c3
Show file tree

Hide file tree

Showing 3 changed files with 243 additions and 4 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -17,7 +17,7 @@ This repo contains the Project Reunion components that are common for all applic
 Look for the **"Project Reunion Family"** badge in other repos showing that their code is 
 using Project Reunion techniques and tooling.  Your own components can be part of the 
 "Project Reunion Family" by following the same principles and practices as Project 
-Reunion itself – support all forms of apps with a single API surface and meet 
+Reunion itself - support all forms of apps with a single API surface and meet 
 developers where they are with the tools they need to build great apps on Windows.
 
 Using Project Reunion will be as simple as adding a reference to our NuGet packages in 
@@ -26,7 +26,7 @@ your build.
 
 # What Project Reunion Brings
 
-Project Reunion functionality comes in three main categories – new APIs, converged APIs, 
+Project Reunion functionality comes in three main categories - new APIs, converged APIs, 
 and API subsets.  Your apps can pick up each different level of functionality **at your 
 own pace**.
 
@@ -88,7 +88,7 @@ existing application style and behaviors.  Whenever possible these APIs will be
 to their existing Windows SDK namespaced APIs, easing the transition to Project Reunion 
 for your existing code.  For existing "flat C" Win32 APIs, an equivalent converged API 
 will be added and then projected to your language and runtime. If you prefer a "flat C" 
-style – or the APIs you want already have a "flat C" expression – we're working on 
+style - or the APIs you want already have a "flat C" expression - we're working on 
 building out a projection of those APIs for you.
 
 As your app migrates to Project Reunion functionality it'll be easier to move between 
@@ -200,7 +200,7 @@ Some functionality will be delivered first as Project Reunion components. As we
 evolving the platform it's important to make sure new functionality & features are available 
 to our developer community just as soon as they're ready to go.  Where there's newer 
 in-platform functionality to use Project Reunion will help you adopt that as soon as it's 
-widely available, without you having to retarget or rewrite – the same Project Reunion API 
+widely available, without you having to retarget or rewrite - the same Project Reunion API 
 surface will continue to work.
 
 As your app uses more Project Reunion functionality it'll be ready for additional targets 

diff --git a/specs/README.md b/specs/README.md
@@ -0,0 +1,84 @@
+# Project Reunion Specs
+
+This directory contains archived and in-progress spec documents for APIs in
+Project Reunion.
+
+Documents in this directory are used as part of a feature or API review
+for features in development and form the basis for public documentation
+and sample code. Write specs so they can be directly consumed by an
+app developer or document author.
+
+## Please DO:
+
+* Provide feedback by **commenting on active pull requests** tagged with
+    [the "ApiReview" label.](https://github.com/microsoft/ProjectReunion/pulls?q=is%3Apr+is%3Aopen+label%3AApiReview)
+* Provide feedback by **opening [issues](https://github.com/microsoft/ProjectReunion/issues/new/choose)
+   regarding spec documents in this folder**.  Specs in this folder
+   are ready for implementation or have already been added to Project Reunion.
+* Create pull requests for new or updated specs when requested to do so
+   as part of an issue thread.
+
+## Please DO NOT:
+
+* Create unsolicited PRs that add or modify  specs. To propose a new feature
+    please follow the Project Reunion contribution process [described here](../docs/contributor-guide.md)
+    and start by [opening a new issue](https://github.com/microsoft/ProjectReunion/issues/new/choose).
+
+## Spec workflow
+
+For Project Reunion team members, the spec and API design workflow is:
+
+1. Ensure your proposal is approved and in plan.
+
+2. Create a new working branch ```user/<username>/<feature>``` or work in
+   your fork of the Project Reunion repo.
+
+3. Create a new folder for your spec under the ```specs``` folder: ```/specs/<feature>```
+
+4. Author your spec using the [spec template](spec_template.md).
+   Please use relative links for images or other assets in the folder.
+   Be sure to read and follow the commented instructions in the template.
+
+5. When your spec is ready for review:
+
+   * Open a new pull request to merge your spec to the ```master``` branch
+   * Reference the issue thread in the pull request to link them together
+
+6. Provide adequate time for the community and Project Reunion members to
+   review the API spec file.
+
+7. Review requested changes with Project Reunion members and the Windows
+   API Design representative responsible for the area.
+
+8. Complete the pull request
+
+This workflow applies to modifying API designs as well.
+
+
+## Specification Notes
+
+**DO** write specification templates as if they will be read by a
+developer trying to understand how to use the API and feature.
+
+**DO** include links to existing types, pointers into https://docs.microsoft.com
+when providing converged features.
+
+**DO** describe how packaged, unpackaged, AppContainer and Full Trust
+applications will use the feature.
+
+**DO NOT** reference Windows-internal features, plans, or scheduling. This
+includes links to internal specifications.
+
+**DO** use "http://task.ms/12345" links if necessary to reference internal
+tasks or deliverable information.
+
+**DO** update existing specifications when adding new functionality,
+rather than creating a new-spec-per-change. Reviewers should read the
+changes to the specification in a pull request.
+
+**DO NOT** gratuitously reformat specification documents, as that can
+obscure real changes vs editorial, whitespace, or other changes.
+
+**DO** specify any additional requirements on application authors, such
+as "you must define an app.config" or "you must include this package
+manifest markup or this application manifest markup" to use a feature.
diff --git a/specs/spec_template.md b/specs/spec_template.md
@@ -0,0 +1,155 @@
+<!--
+    Before submitting, delete all <!-- TEMPLATE marked comments in this file,
+    and the following quote banner:
+-->
+> See comments in Markdown for how to use this spec template
+
+<!-- TEMPLATE
+    The purpose of this spec is to describe a new feature and
+    its APIs that make up a new feature in Project Reunion. 
+
+    There are two audiences for the spec. The first are people
+    that want to evaluate and give feedback on the API, as part of
+    the submission process.  When it's complete
+    it will be incorporated into the documentation for Project Reunion.
+    Hopefully we'll be able to copy it mostly verbatim.
+    So the second audience is everyone that reads there to learn how
+    and why to use this API. 
+-->
+
+# Background
+
+<!-- TEMPLATE
+    Use this section to provide background context for the new API(s)
+    in this spec. 
+
+    This section and the appendix are the only sections that likely
+    do not get copied into any official documentation, they're just an aid
+    to reading this spec. 
+    
+    If you're modifying an existing API, included a link here to the
+    existing page(s) or spec documentation.
+
+    For example, this section is a place to explain why you're adding this
+    API rather than modifying an existing API.
+
+    If you're writing a "converged" API add links into docs.microsoft.com
+    for the existing Win32 or WinRT APIs that are being converged.
+-->
+
+<!-- TEMPLATE
+    For example, this is a place to provide a brief explanation of some dependent
+    area, just explanation enough to understand this new API, rather than telling
+    the reader "go read 100 pages of background information posted at ...". 
+-->
+
+# Description
+
+<!-- TEMPLATE
+    Use this section to provide a brief description of the feature.
+    For an example, see the introduction to the PasswordBox control
+    (http://docs.microsoft.com/windows/uwp/design/controls-and-patterns/password-box).
+-->
+
+# Examples
+
+<!-- TEMPLATE
+
+    Use this section to explain the features of the API, showing
+    example code with each description. The general format is:
+
+    ## FirstFeatureName
+
+    Feature explanation text goes here, including why an app would use it, how it
+    replaces or supplements existing functionality.
+
+    ```c#
+    void SampleMethod() {
+        var show = new AnExampleOf();
+        show.SomeMembers = AndWhyItMight(be, interesting)
+    }
+    ```
+
+    ## SecondFeatureName
+
+    Feature explanation text goes here, including why an app would use it, how it
+    replaces or supplements existing functionality.
+
+    ```c#
+    void SampleMethod() {
+        var show = new AnExampleOf();
+        show.SomeMembers = AndWhyItMight(be, interesting)
+    }
+    ```
+
+    Code samples should be in C# and/or C++/WinRT.
+
+    As an example of this section, see the Examples section for the PasswordBox
+    control (https://docs.microsoft.com/windows/uwp/design/controls-and-patterns/password-box#examples). 
+-->
+
+# Remarks
+
+<!-- TEMPLATE
+
+    Explanation and guidance that doesn't fit into the Examples section.
+
+    APIs should only throw exceptions in exceptional conditions; basically,
+    only when there's a bug in the caller, such as argument exception.  But if for some
+    reason it's necessary for a caller to catch an exception from an API, call that
+    out with an explanation either here or in the Examples
+-->
+
+# API Notes
+
+<!-- TEMPLATE
+
+    Option 1: Give a one or two line description of each API (type and member),
+        or at least the ones that aren't obvious from their name. These
+        descriptions are what show up in IntelliSense. For properties, specify
+        the default value of the property if it isn't the type's default (for
+        example an int-typed property that doesn't default to zero.) 
+        
+    Option 2: Put these descriptions in the below API Details section,
+        with a "///" comment above the member or type. 
+-->
+
+# API Details
+
+<!-- TEMPLATE
+
+    The exact API, in MIDL3 format (https://docs.microsoft.com/en-us/uwp/midl-3/)
+    when possible, or in C# if starting with an API sketch.  GitHub's markdown
+    syntax formatter does not (yet) know about MIDL3, so use ```c# instead even
+    when writing MIDL3.
+
+    Example:
+
+    ```c# (but really MIDL3)
+    namespace Microsoft.AppModel
+    {
+        /// Represents a package on the host system. See Windows.ApplicationModel.Package for more details
+        runtimeclass Package
+        {
+            /// Returns the current package, or null if the current process is not packaged
+            static Package Current { get; };
+
+            /// Returns the package from the system store with this full name or null if not found
+            static Package GetFromFullName(String fullName);
+
+            /// Returns packages in the given family, by name
+            static Package[] FindByFamilyName(String familyName);
+        }
+    }
+    ```
+-->
+
+# Appendix
+
+<!-- TEMPLATE
+
+    Anything else that you want to write down for posterity, but
+    that isn't necessary to understand the purpose and usage of the API.
+    For example, implementation details.
+    
+-->