Add design considerations and clarify process (microsoft#46)

This update adds new documents on design considerations and contact information.

The design considerations document tries to codify some of the basic design language for HLSL and cover common topics that features will need to address in their specification.

This also updates some wording and details around the process docs and specifically about proposal sponsors. We think it is important that Vulkan-specific proposals have a sponsor from the Vulkan Working Group, so that is explicitly stated.

docs/Contact.md

@@ -0,0 +1,24 @@
+# Contacting the HLSL Team
+
+This page lists some of the public spaces where you can find members of the HLSL.
+
+## Discord Channels
+
+* [DirectX](https://discord.com/invite/directx) - For D3D related
+  HLSL topics.
+* [LLVM](https://discord.gg/xS7Z362) - For HLSL Compiler Modernization and other
+  compiler topics.
+
+## GitHub Issues
+
+* [DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/issues/new)
+  - For bugs and feature requests specific to the DXC compiler.
+* [hlsl-specs](https://github.com/microsoft/hlsl-specs/issues/new) - For feature
+  requests for the HLSL language or runtimes (Shader Models, Vulkan, etc).
+* [LLVM](https://github.com/llvm/llvm-project/issues/new) - For bugs and feature
+  requests specific to the Clang HLSL implementation.
+
+## Email
+
+* [Ask HLSL](mailto:[email protected]) - For issues where privacy is
+  essential.

docs/DesignConsiderations.md

@@ -0,0 +1,82 @@
+# HLSL Design Considerations
+
+When designing and proposing a feature for HLSL there are some design
+considerations that should be taken into account.
+
+## Style Conventions
+
+HLSL's built-in types and methods should conform to a consistent coding style.
+
+* Data types, methods and built-in functions should all be `CamelCase`.
+* Namespaces and keywords are lowercase, `_` separated.
+* Vulkan-specific functionality should be added to the `vk` namespace.
+* Microsoft-style attributes interchangably use `CamelCase` and `_` separation,
+  but should prefer `CamelCase`
+* System Value semantics are case insensitive, should be specified `CamelCase`
+  and prefixed `SV_`.
+
+## Versioning
+
+All features should consider how users can adapt to the presence or absence of
+support. HLSL has two primary revisioning axis: language version and runtime
+version. How the two versions interact is not always a clean and easy line to
+see.
+
+### Language Changes
+
+> Language versioning changes the core language of HLSL: syntax, grammar,
+> semantics, etc.
+
+HLSL identifies language versions by the year of release (2015, 2016, 2017,
+2018, 2021, ...), and future language versions have placeholder years (202x,
+202y, ...).
+
+Most language features do not require underlying runtime features so they can be
+exposed in HLSL regardless of runtime targeting.
+
+Some HLSL language features are _strictly additive_, and may be retroactively
+enabled in older language modes. See the section below on "Exposing versioning"
+for more information about retroactively exposing features.
+
+### Runtime Changes
+
+> Runtime versioning changes the library functionality of the language: data
+> types, methods, etc.
+
+HLSL's supported runtimes are DirectX and Vulkan. For DirectX versioning of HLSL
+is broken down by Shader Model and DXIL version, and for Vulkan versioning is
+broken down by Vulkan and SPIR-V version.
+
+When a new runtime version is released and no previous HLSL compilers have
+supported it, the feature can be added dependent only on targeting the new
+runtime version. When a feature is added to a runtime version that has
+previously been supported by a compiler release, the feature should be treated
+as a retroactive addition. See the section below on "Exposing versioning" for
+more information about retroactively exposing features.
+
+### Exposing versioning
+
+HLSL language and target runtime versions are exposed in the HLSL preprocessor
+via the built-in preprocessor macros described below:
+
+* **`__HLSL_VERSION`** - Integer value for the HLSL language version. Unreleased
+  or experimental language versions are defined as a number larger than the
+  highest released version.
+* **`__SHADER_TARGET_STAGE`** - Integer value corresponding to the shader stage.
+  Shader stage. The shader stage values are exposed as
+  `__SHADER_STAGE_**STAGE**` (i.e. `__SHADER_STAGE_VERTEX`,
+  `__SHADER_STAGE_PIXEL`, ...)
+* **`__SHADER_TARGET_MAJOR`** - Major version for Shader Model target.
+* **`__SHADER_TARGET_MINOR`** - Minor version for Shader Model target.
+
+If these macros are not sufficient for a given feature new macros or other
+mechanisms should be added as appropriate for the feature to enable developers
+to know if a given compiler release supports the required feature(s).
+
+For features that are added retroactively to an already final runtime or
+language version, a `__has_feature` check should be added to allow the user to
+query for feature support in the preprocessor instead of forcing the user to
+check compiler versions explicitly. The Clang feature checking macros are
+documented
+[here](https://clang.llvm.org/docs/LanguageExtensions.html#feature-checking-macros).
+The `__has_feature` macro is known to work in DXC, and should be used.

docs/Process.md

@@ -6,13 +6,11 @@ Despite the openness of this process there are three significant caveats that
 should be noted:
 
 1. Final decisions about what features are included or excluded from HLSL are
-  made by the MSFT HLSL Team.
-2. This process cannot be used for features that require Shader Model changes
-  because Shader Model collaboration with hardware vendors occurs in private
-  under NDA.
-3. Some HLSL features may not go through this process, and may be kept secret
-  during development. We will try to restrict this only to features that require
-  NDAs with hardware vendors, but that may not always be the reason.
+   made by the MSFT HLSL Team. Our goals are to make HLSL the best programming
+   language across all supported runtime targets, not just DirectX or Vulkan.
+2. Some HLSL features may not go through this process, and may be kept secret
+   during development. We will try to restrict this only to features that
+   require NDAs with hardware vendors, but that may not always be the reason.
 
 Feature proposals from outside the HLSL team will be interpreted as requests,
 and may be considered or rejected based on team and release priorities. You
@@ -31,15 +29,30 @@ further tweaked to align with the HLSL team's goals and priorities.
 ## Proposing a Feature
 
 By far the best way for an external contributor to propose a feature is through
-GitHub issues (See the section below on "Filing Issues"). If you can't be
-deterred from writing a proposal yourself you must find a member of the HLSL
-team to act as a _Sponsor_ for the change. The _Sponsor_ is responsible for
-tracking and helping change proposals through the proposal life cycle.
+GitHub issues (See the section below on "Filing Issues"). Issues in this
+repository will be used to publicly track feature requests for the HLSL language
+and HLSL runtime interfaces. Direct tooling feature requests to the
+[DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/issues/new).
+
+> Note: a tooling feature would be a feature that does not impact HLSL source
+> representations in any way (no added syntax, APIs, or altered
+> interpretations), and instead exposes new ways to use the DXC compiler or
+> library.
+
+If you write a proposal yourself you must find a member of the HLSL team to act
+as a _Sponsor_ for the change. The _Sponsor_ is responsible for tracking and
+helping change proposals through the proposal life cycle. For Vulkan-specific
+features we require at least one _Sponsor_ from the HLSL team and one _Sponsor_
+from the Khronos Vulkan Working Group. If you need assistance finding a
+_Sponsor_ for a proposal reach out to the [HLSL Team](Contact.md).
 
 All feature proposals are evaluated against the goals for the next HLSL language
 revision. The goals for the upcoming HLSL language version can be found
 [here](HLSL202x.md).
 
+When writing a feature proposal you should also familiarize yourself with the
+HLSL [Design Considerations](DesignConsiderations.md).
+
 ## Proposal Lifecycle
 
 Draft proposals are first provided as pull requests. They should be written