Merging to master

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+Thank you for contributing to XAML Standard! We are at the **_very early stages_** of a long term collaboration towards a unified XAML vocabulary that all XAML developers can comfortably rely on to target all your desired end points.
+
+## All submissions
+- [ ] Have you read the [principles](https://github.com/Microsoft/xaml-standard/blob/staging/docs/reviewboard.md#principles)?
+- [ ] Have you checked that your post fits the [nature of proposals](https://github.com/Microsoft/xaml-standard/blob/staging/docs/proposalsfaq.md#nature-of-a-proposal)?
+- [ ] Have you checked to ensure that there aren't other open [issues](https://github.com/Microsoft/xaml-standard/issues) for the same topic?
+- [ ] Have you followed the [contributor code of conduct](https://dotnetfoundation.org/code-of-conduct)?
+
+## If you are posting an API for XAML standard consideration:
+- Add a brief overview of what you are proposing and why it belongs in XAML Standard (in keeping with the principles of the effort).
+- Provide a clear usecase/scenario that describes how this API benefits in sharing cross-platform UI code, preferably a scenario from your experience or application that clearly illustrates why a control/API would benefit from being standardized.
+- Add a brief example in XAML syntax for your proposal.
+- Provide links to issues/discussions where this proposal has been talked about as well as any other pointer to where this originated or got discussed that could describe the motivation.
+
+For discussions that are not concrete proposals, please prefix title with "Discussion" so we can categorize accordingly.

README.md

@@ -1,17 +1,42 @@
 # XAML Standard
 
-This repository contains the principles and definition of XAML Standard.
+## Updates: 
+_Thank you for patiently bearing with us as we have been iterating over feedback and working to better define the principles for XAML Standard._
+
+## Principles: 
 
-XAML Standard is a vocabulary spec that defines a standard XAML vocabulary. Frameworks that support XAML standard can share common XAML based UI definitions. 
+* Different platforms have different personalities and capabilities.  For the best end-user experience, developers build native apps that embrace the native personalities and capabilities of the platforms and device form factors.  
+* **Xamarin** and **Xamarin.Forms** are optimized for developers building native mobile scenarios and focuses on exposing the common and abstracted subset of controls and capabilities most needed by mobile developers.
+* **Windows 10 XAML** and **WPF** are optimized for native Windows experiences and focuses on exposing the full and unique capabilities of the Windows platform.  Developers empowered with **Windows 10 XAML** and **WPF**, can harness the full and unique capabilities of the Windows platform, including the most rich and demanding experiences optimized for use with mouse, keyboard and touch.
+* We will continue to optimize **Xamarin.Forms** as an abstraction layer for native mobile development and optimize **Windows 10 XAML** and **WPF** for Windows native experiences.  
 
-The goal is for the first version, XAML Standard 1.0, to be available later this year.  Post specification plans include support of XAML standard in Xamarin Forms and UWP.  
+## Revised definition and scope: 
 
-For more information, read the [faqs](docs/faq.md)
+* XAML Standard is an alignment effort targeted at finding the right middle ground of concepts and tags that can be shared between Microsoft’s XAML UI systems to make it easier to work with XAML regardless of target platforms.
+* XAML Standard is set of principles that drive XAML dialect alignment and not a product or product feature.  For more details on the updated principles, see [Principles](docs/reviewboard.md#principles)
+
+## Timeframe: 
+As a first phase of alignment, we are making a set of additive updates to Windows 10 XAML and Xamarin.Forms. For example: 
+* TextBlock, StackPanel (and several other tags as requested here) are being added to Xamarin.Forms - see [aka.ms/xf-xamlstandard](<https://aka.ms/xf-xamlstandard>) for details on how you can try these out. 
+* Similarly ease of use APIs like StackPanel.Spacing etc., are being added to Windows 10 XAML. 
+
+For the full list of aligned tags at this time, see [here](docs/v1draft.md).
+
+With this clarified stance, we will be more active on the Issues and help provide more clarity on the goals and timelines. We encourage you to continue providing us feedback on concepts and tags that would benefit from closer alignment to serve your scenarios.
+
+For more information, read the [faqs](docs/faq.md).
 
 ## How to engage, contribute and provide feedback
 
-This spec is being designed in the open. We are in the early stages of defining the spec right now, you can see a draft of XAML Standard 1.0 getting defined [here](docs/v1draft.md). We encourage you to start a discussion or give us direct feedback by [filing an issue](https://github.com/Microsoft/xaml-standard/issues) or [starting a proposal](https://github.com/Microsoft/xaml-standard/labels/proposal)
+We encourage you to start a discussion or give us direct feedback by [filing an issue](https://github.com/Microsoft/xaml-standard/issues) or [starting a proposal](https://github.com/Microsoft/xaml-standard/labels/proposal). 
 
-This project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/) to clarify expected behavior in our community. For more information, see the [.NET Foundation Code of Conduct](http://www.dotnetfoundation.org/code-of-conduct).
+### _If you are posting an API for XAML standard consideration:_
+- Mark it with the label: "proposal". 
+- Add a brief overview of what you are proposing and why it belongs in XAML Standard alignment effort (in keeping with the principles of the effort).
+- Provide a clear usecase/scenario that describes how this API benefits in sharing across XAML UI platforms, preferably a scenario from your experience or application that clearly illustrates why a control/API would benefit from being aligned.
+- Add a brief example in XAML syntax for your proposal.
+- Provide links to issues/discussions where this proposal has been talked about as well as any other pointer to where this originated or got discussed that could describe the motivation.
 
+See [proposals-faq](docs/proposalsfaq.md) for more information.
 
+This project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/) to clarify expected behavior in our community. For more information, see the [.NET Foundation Code of Conduct](http://www.dotnetfoundation.org/code-of-conduct).

docs/faq.md

@@ -1,19 +1,32 @@
 # FAQs
 
+## Additional resources
+* **NEW!!** [Xamarin.Forms - XAML Standard preview](https://developer.xamarin.com/guides/xamarin-forms/xaml/standard/) 
+* [Introducing XAML Standard and .NET Standard 2.0 blog](https://blogs.windows.com/buildingapps/2017/05/19/introducing-xaml-standard-net-standard-2-0)
+* [Ch9 Interview with Tim Heuer, Scott Hunter and Miguel de Icaza](https://developer.microsoft.com/en-us/windows/projects/events/build/2017/net-standard-20-uwp-support-and-ui-features)
+
 ## What is XAML Standard?
-XAML Standard is a vocabulary specification that defines a standard XAML markup vocabulary. Frameworks that support XAML Standard can share common XAML based UI definitions. 
+XAML Standard is an alignment effort to improve productivity for developers creating UI with Windows10 XAML and Xamarin.Forms. It is targeted at finding the right middle ground of concepts and tags that can be shared between Microsoft’s XAML UI systems - Windows10 XAML, WPF and Xamarin.Forms to make it easier to work with XAML regardless of target platforms.
+
+## What is the relationship between XAML Standard, Windows10 XAML, WPF and Xamarin.Forms?
+* XAML Standard is set of principles that drive XAML dialect alignment and not a product or product feature.  
+* Windows10 XAML, WPF and Xamarin Forms are concrete frameworks that implement the XAML Standard. 
+* We will continue to optimize Xamarin.Forms as an abstraction layer for native mobile development and optimize Windows 10 XAML and WPF for Windows native experiences
 
-The goal is for the first version, XAML Standard 1.0, to be available later this year. Post specification plans include support of XAML standard in Xamarin.Forms and UWP.
+## What can I do after XAML Standard that I couldn’t do before?
+We are at the beginning of a journey that makes it easy for you to align concepts between Xamarin.Forms, Windows10 XAML and even WPF to a large extent. For example - once Phase1 of XAML Standard is supported by Xamarin.Forms, you can use `<TextBlock/>` in your markup and have it supported in a Xamarin.Forms app targeting iOS and Android instead of needing to know and use `<Label/>` like you did before.
 
-## What is the relationship between XAML Standard, UWP, Xamarin.Forms?
-* XAML Standard is the specification document that defines which APIs and schema concepts a XAML based framework needs to implement.
-* UWP and Xamarin Forms are concrete frameworks that implement the XAML Standard. 
+## What should I do if I develop Windows10, WPF or Xamarin.Forms apps today?
+Nothing changes for existing developers - you can continue to use the same APIs you have always used in all three frameworks. The XAML Standard effort will help you reuse some of the common UI tags and concepts between Microsoft's XAML UI frameworks that were previously misaligned.
 
-## What can I do with XAML Standard that I couldn’t do before?
-We are at the beginning of a journey that makes it easy for you to reuse your XAML source files between Xamarin.Forms, UWP and even WPF to a large extent. For example - once XAML Standard is supported by Xamarin.Forms, you can use `<TextBlock/>` in your markup and have it supported in a Xamarin.Forms app targeting iOS and Android instead of needing to know and use `<Label/>` like you did before.
+## Where can I try this out?
+XAML Standard is not a product, but an alignment effort we are embarking on. 
+* Windows10 Fall creators update included newly aligned properties in Windows10 XAML to match some Xamarin.Forms affordances.
+* Check out [aka.ms/xf-xamlstandard](<https://aka.ms/xf-xamlstandard>) for a preview of newly aligned tags in Xamarin.Forms to match Windows10 XAML.
 
-## What should I do if I develop UWPs or Xamarin.Forms apps today?
-Nothing changes for existing developers - you can continue to use the same APIs you have always used in both frameworks. XAML Standard will help you reuse/share any common UI code that you wish to share between frameworks.
+## Who decides what goes in the Standard?
+The feedback and proposals from this repo are inputs into the overall decision making process. We are starting with a small review board outlined [here](reviewboard.md). The principles behind what goes in the standard are outlined [here](reviewboard.md#principles).
 
 ## How can I participate?
-We are in the early stages of defining the spec right now, you can see a draft of XAML Standard 1.0 getting defined [here](docs/v1draft.md). We encourage you to start a discussion or give us direct feedback by [filing an issue](https://github.com/Microsoft/xaml-standard/issues) or [starting a proposal](https://github.com/Microsoft/xaml-standard/labels/proposal) for what you would like to see in v1 and beyond.
+ We encourage you to start a discussion or give us direct feedback by [filing an issue](https://github.com/Microsoft/xaml-standard/issues) or [starting a proposal](https://github.com/Microsoft/xaml-standard/labels/proposal) for what you would like to see aligned. Read the [proposals-faq](proposalsfaq.md) for more information.
+

docs/proposalsfaq.md

@@ -0,0 +1,28 @@
+# XAML Standard proposals
+
+XAML Standard proposals are filed as issues serving as living documents describing the current thinking about a XAML feature/API. 
+
+## Lifetime of a proposal
+
+Proposals start their life as an [issue:proposal](https://github.com/Microsoft/xaml-standard/labels/proposal). Through its lifetime proposals can be either *accepted*, *rejected* or *inactive*. [Accepted](https://github.com/Microsoft/xaml-standard/labels/accepted) proposals will be tagged with a specific [milestone](https://github.com/Microsoft/xaml-standard/milestones) to indicate which version of the Standard will surface the feature/API.
+
+If we want to capture an idea without wanting to work on it right now, a proposal can start out as *inactive*. Proposals may even start out directly in the *rejected* state, if we want to make a record of something we don't intend to do. For instance, if a popular and recurring request is not possible to implement, we can capture that as a rejected proposal.
+
+A proposal is considered *active* if it is moving forward through design. Once it is completely done, i.e. the feature has been completely specified, it will be moved into a subdirectory corresponding to its version.
+
+If a proposal turns out not to be likely to make it into the Standard at all, e.g. because it proves unfeasible, does not seem to add enough value or just isn't right for the Standard, it will be [rejected](https://github.com/Microsoft/xaml-standard/labels/rejected). If a proposal has reasonable promise but is not currently being prioritized to specify, it may be declared [inactive](https://github.com/Microsoft/xaml-standard/labels/inactive). It is perfectly fine for conversation to happen on inactive or rejected proposals, and for them to be resurrected later. The categories are there to reflect current design intent.
+
+## Nature of a proposal
+
+A proposal should follow the [principles](reviewboard.md#principles) of XAML Standard. A good proposal should:
+
+- Fit with the general spirit and aesthetic of the XAML Standard.
+- Not introduce subtly alternate syntax for existing features.
+- Add a lot of value for a clear set of users.
+- Not add significantly to the complexity of the XAML Standard, especially for new users.  
+
+## Discussion of proposals
+
+Feedback and discussion happens in [issues](https://github.com/Microsoft/xaml-standard/issues). 
+
+

docs/reviewboard.md

@@ -0,0 +1,20 @@
+# XAML Standard Review Board
+The primary goal is alignment of dialects between Microsoft XAML UI systems. Hence, the decision maker is Microsoft with input on what is desired from the broader community here. The review board at this time includes representatives from **Windows10 XAML** and **Xamarin.Forms** teams.
+
+## Principles
+* XAML Standard is an alignment effort targeted at finding the right middle ground of concepts and tags that can be shared between Microsoft’s XAML UI systems (Windows10 XAML, WPF and Xamarin.Forms)
+* XAML Standard is set of principles that drive XAML dialect alignment and not a product or product feature.
+
+Not every XAML API needs to be part of the XAML Standard effort. The following principles will be applied in determining what will and will not be a part of the alignment effort. 
+
+* **Widely used APIs** In order to enable a vibrant XAML based ecosystem, it's important to have a common vocabulary of the most widely used tags that XAML developers can comfortably rely on. The XAML Standard effort will include such widely used APIs to enable maximum reuse.
+
+* **Ubiquitous APIs** The XAML Standard effort represents the unified common subset of XAML tags and concepts that is universal to all platforms and could be made available everywhere without compromising on enabling native user experiences.
+  * Any API or concept that does not empower building of native mobile and desktop user experiences will be excluded from the standard effort. For example: Button.Content allowing any UI content will not be part of the alignment effort since such a content model is not native to iOS and Android Button control models.
+  * Any API or concept that is fundamentally tied to a specific native implementation/technology will be excluded from the standard effort. For example: A Windows Hello based login control will not be part of XAML Standard.
+  * Frameworks can add to what is prescribed by the XAML Standard. For example: XAML Standard Slider definition may not include an Orientation property. Windows10 XAML implementation of Slider can include that.
+
+* While the standard effort does not mandate how the APIs are implemented, it is expected that the frameworks respect the most intuitive and common behavior of the API while implementing the same in order for XAML developers to be able to reasonably rely on definitions. For example: 'Grid.RowSpan=”2”' must do the expected thing across all frameworks that support the standard.
+  * This will be honored within reason – the Standard effort will not impose pixel perfect behavior matching across all XAML based UI frameworks.
+
+