diff --git a/docs/Process.md b/docs/Process.md index 7d2f2c42..428b1ba0 100644 --- a/docs/Process.md +++ b/docs/Process.md @@ -26,18 +26,13 @@ This process draws heavily 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 +Significant project infrastructure or implementation details will also use this +process to refine and document the design process. -By far the best way for an external contributor to propose a feature is through -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). +## Making a Proposal -> 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. +The best way for an external contributor to propose a feature is through GitHub +issues (See the section below on "Filing Issues"). 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 @@ -58,6 +53,10 @@ HLSL [Design Considerations](DesignConsiderations.md). Draft proposals are first provided as pull requests. They should be written following one of the templates in the `proposals/templates` directory. +Add new proposals for language or runtime features directly in the `proposals` +directory. Add new proposals for project infrastructure or implementation +details of the compilers in the `proposals/infra` directory. + Proposals that follow the most simplified path from idea to feature will move through the following states in order: @@ -94,6 +93,19 @@ requirements for justification are not high and could be as simple as ## Filing Issues +Issues in this repository publicly tracks feature requests for the HLSL language +and HLSL runtime interfaces as well as issues with proposals and specifications +contained within the repository. + +Please direct tooling feature requests to the +[DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/issues/new), +or [Clang](https://github.com/llvm/llvm-project/issues/new) as appropriate. + +> 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. + This repository provides three custom issue templates: 1. Feature Request diff --git a/proposals/infra/index.md b/proposals/infra/index.md new file mode 100644 index 00000000..ab7a1654 --- /dev/null +++ b/proposals/infra/index.md @@ -0,0 +1,8 @@ +# Current Active Proposals + +{% assign doclist = site.pages | sort: 'url' %} +{% for doc in doclist %} +{% if doc.name contains '.md' and doc.dir == '/proposals/' and doc.name != 'index.md' %} +* [{{ doc.name }}]({{ doc.url | relative_url }}) +{% endif %} +{% endfor %} diff --git a/proposals/templates/infrastructure-template.md b/proposals/templates/infrastructure-template.md new file mode 100644 index 00000000..7ce93118 --- /dev/null +++ b/proposals/templates/infrastructure-template.md @@ -0,0 +1,76 @@ + + +# Feature name + +## Instructions + +> This template wraps at 80-columns. You don't need to match that wrapping, but +> having some consistent column wrapping makes it easier to view diffs on +> GitHub's review UI. Please wrap your lines to make it easier to review. + +> When filling out the template below for a new feature proposal, please do the +> following first: + +> 1. exclude the "Planned Version", "PRs" and "Issues" from the header. +> 2. Do not spend time writing the "Detailed design" until the feature has been +> merged in the "Under Consideration" phase. +> 3. Delete this Instructions section including the line below. + +--- + +* Proposal: [NNNN](NNNN-filename.md) +* Author(s): [Author 1](https://github.com/author_username) +* Sponsor: TBD +* Status: **Under Consideration** +* Impacted Project(s): (DXC, Clang, etc) + +*During the review process, add the following fields as needed:* + +* 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 a problem 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 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: + +* Is there any potential for changed behavior? +* Will this expose new interfaces that will have support burden? +* How will this proposal be tested? +* Does this require additional hardware/software/human resources? + +## 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. + +