From d296f4aea03a7043eb8577181e56b25117d1a5f5 Mon Sep 17 00:00:00 2001 From: Chris Bieneman Date: Tue, 6 Sep 2022 12:59:19 -0500 Subject: [PATCH] Initial commit of process docs This commit adds the initial process documentation and templates. This should get the ball rolling for us. --- README.md | 14 ++---- SUPPORT.md | 17 ++----- docs/HLSL202x.md | 15 +++++++ docs/Process.md | 65 +++++++++++++++++++++++++++ proposals/templates/basic-template.md | 58 ++++++++++++++++++++++++ 5 files changed, 144 insertions(+), 25 deletions(-) create mode 100644 docs/HLSL202x.md create mode 100644 docs/Process.md create mode 100644 proposals/templates/basic-template.md diff --git a/README.md b/README.md index 5cd7cecf..dbe9e356 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,7 @@ -# Project - -> This repo has been populated by an initial template to help get you started. Please -> make sure to update the content to build a great experience for community-building. - -As the maintainer of this project, please make a few updates: - -- Improving this README.MD file to provide a great experience -- Updating SUPPORT.MD with content about this project's support experience -- Understanding the security reporting process in SECURITY.MD -- Remove this section from the README +# HLSL Specifications +This repository contains documentation for HLSL feature proposals and specifications. Please see the documentation for +the HLSL Feature [Proposal Process](docs/Process.md) for more information on proposals. ## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a diff --git a/SUPPORT.md b/SUPPORT.md index 291d4d43..86745ca3 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,13 +1,3 @@ -# TODO: The maintainer of this repo has not yet edited this file - -**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project? - -- **No CSS support:** Fill out this template with information about how to file issues and get help. -- **Yes CSS support:** Fill out an intake form at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). CSS will work with/help you to determine next steps. -- **Not sure?** Fill out an intake as though the answer were "Yes". CSS will help you decide. - -*Then remove this first heading from this SUPPORT.MD file before publishing your repo.* - # Support ## How to file issues and get help @@ -16,10 +6,9 @@ This project uses GitHub Issues to track bugs and feature requests. Please searc issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new Issue. -For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE -FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER -CHANNEL. WHERE WILL YOU HELP PEOPLE?**. +For help and questions about using this project, please reach out to +[HLSL Support](mailto:AskHLSL@microsoft.com). ## Microsoft Support Policy -Support for this **PROJECT or PRODUCT** is limited to the resources listed above. +Support for this HLSL Specifications is limited to the resources listed above. diff --git a/docs/HLSL202x.md b/docs/HLSL202x.md new file mode 100644 index 00000000..2e763a93 --- /dev/null +++ b/docs/HLSL202x.md @@ -0,0 +1,15 @@ +# HLSL 202x + +HLSL 202x is the working name for the language version that will succeed HLSL +2021. + +The primary goal of HLSL 202x is to make the language more regular, more +consistent with C++, and to codify language behaviors in a describable and +understandable way for users. + +The proposed features for HLSL 202x are a combination of new features for the +language to improve compatibility with C++, and the removal of old features +which caused inconsistency. + +As a secondary goal, HLSL 202x strives to make language behaviors more regular +to aid in a long term goal of producing a formal language specification. diff --git a/docs/Process.md b/docs/Process.md new file mode 100644 index 00000000..56a75db4 --- /dev/null +++ b/docs/Process.md @@ -0,0 +1,65 @@ +# Proposal Process + +The HLSL feature process is not open to public contribution. This repository +exists in order to provide visibility and solicit feedback. + +Feature proposals from outside the HLSL team will be interpreted as requests, +and may be considered or rejected based on team and release priorities. The best +way for users to request features for HLSL is to file GitHub issues rather than +creating pull requests against this repository. + +This process draws heavily from +[Rust's RFC process](https://github.com/rust-lang/rfcs), and from +[Swift's Evolution process](https://github.com/apple/swift-evolution/), and is +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. 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. + +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). + +## Proposal Lifecycle + +Draft proposals are first provided as pull requests. They should be written +following one of the templates in the `proposals/templates` directory. + +Proposals that follow the most simplified path from idea to feature will move +through the following states in order: + +* **Under Consideration** - All proposed features start in this state. While + under consideration features are reviewed by members of the HLSL team and + feedback is solicited from users and hardware vendors. + +* **Under Review** - If a feature is deemed to be in alignment with the release + goals, and of value to the community a feature may be promoted to being under + review. During this time, a feature specification must be drafted, revised, + and accepted. + +* **Accepted** - Once a feature is accepted it becomes a planned feature for the + release. At this time changes to enable the feature under the new language + mode can begin landing in the HLSL compiler. The Accepted state does not mean + the feature will ship in the planned release. There are a variety of reasons + why features may not make the final release, but it does signify an intent to + bring the feature into the release. + +* **Completed** - Once a feature is fully implemented in the main compiler + branch under the appropriate language version, the proposal completed. + +Additionally feature proposals may end up in the **Rejected** or **Deferred** +states. + +**Rejected** features are features that will not be included in HLSL. All +rejected features will be appended with a detailed reasoning explaining the +rationale behind why the feature was rejected. + +**Deferred** features can occur for a variety of reasons. Features that are +deferred may be provided with some justification for the deferral although the +requirements for justification are not high and could be as simple as +"insufficient resources". diff --git a/proposals/templates/basic-template.md b/proposals/templates/basic-template.md new file mode 100644 index 00000000..ec0e9314 --- /dev/null +++ b/proposals/templates/basic-template.md @@ -0,0 +1,58 @@ +# Feature name + +* Proposal: [NNNN](NNNN-filename.md) +* Author(s): [Author 1](https://github.com/author_username) +* Sponsor: TBD +* Status: **Under Consideration** + +*During the review process, add the following fields as needed:* + +* Planned Version: 20YY +* PRs: [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/pull/NNNN) +* Issues: + [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/issues/NNNN) + +## Introduction + +10,000 ft view of the change being proposed. Try to keep to one paragraph and +less than 10 sentences. + +## Motivation + +Describe the problems users are currently facing that this feature addresses. +Include concrete examples, links to related issues, and any relevant background. + +The point of this section is not to convince reviewers that you have a solution, +but rather that HLSL has a problem that needs to be resolved. + +## Proposed solution + +Describe your solution to the problem. Provide examples and describe how they +work. Show how your solution is better than current workarounds: is it cleaner, +safer, or more efficient? + +## Detailed design + +_The detailed design is not required until the feature is under review._ + +This section should grow into a feature specification that will live in the +specifications directory once complete. Each feature will need different levels +of detail here, but some common things to think through are: + +* How is this feature represented in the grammar? +* How does it work interact other HLSL features (semantics, buffers, etc)? +* How does this interact with C++ features that aren't already in HLSL? +* Does this have implications for existing HLSL source code compatibility? +* Does this change require DXIL changes? +* Can it be CodeGen'd to SPIR-V? + +## Alternatives considered (Optional) + +If alternative solutions were considered, please provide a brief overview. This +section can also be populated based on conversations that occur during +reviewing. + +## Acknowledgments (Optional) + +Take a moment to acknowledge the contributions of people other than the author +and sponsor.