From db6623f9bcb37e18b7d791be2b9185e502947891 Mon Sep 17 00:00:00 2001 From: Chris B Date: Tue, 9 Jan 2024 16:33:44 -0600 Subject: [PATCH] Update process for infrastructural proposals (#131) This updates the process docmentation and adds a new template for describing infrastructural proposals. This will allow us to use this process format for desigining project infrastructure and implementation details within the tooling that may not have language or other user exposure. --- docs/Process.md | 32 +++++--- proposals/infra/index.md | 8 ++ .../templates/infrastructure-template.md | 76 +++++++++++++++++++ 3 files changed, 106 insertions(+), 10 deletions(-) create mode 100644 proposals/infra/index.md create mode 100644 proposals/templates/infrastructure-template.md 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. + +