Skip to content

Commit 6a73640

Browse files
llvm-beanzV-FEXrt
andauthored
Update DXC's CONTRIBUTING file (microsoft#7265)
This change seeks to address some recent questions about how the LLLVM Coding Standards are applied in DXC. --------- Co-authored-by: Ashley Coleman <ascoleman@microsoft.com>
1 parent 9010244 commit 6a73640

File tree

1 file changed

+23
-1
lines changed

1 file changed

+23
-1
lines changed

CONTRIBUTING.md

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,32 @@ Before submitting a feature or substantial code contribution please discuss it w
4040

4141
### Coding guidelines
4242

43-
The coding, style, and general engineering guidelines follow those described in the docs/CodingStandards.rst. For additional guidelines in code specific to HLSL, see the docs/HLSLChanges.rst file.
43+
The coding, style, and general engineering guidelines follow those described in the [LLVM Coding Standards](docs/CodingStandards.rst). For additional guidelines in code specific to HLSL, see the [HLSL Changes](docs/HLSLChanges.rst) docs.
4444

4545
DXC has adopted a clang-format requirement for all incoming changes to C and C++ files. PRs to DXC should have the *changed code* clang formatted to the LLVM style, and leave the remaining portions of the file unchanged. This can be done using the `git-clang-format` tool or IDE driven workflows. A GitHub action will run on all PRs to validate that the change is properly formatted.
4646

47+
#### Applying LLVM Standards
48+
49+
All new code contributed to DXC should follow the LLVM coding standards.
50+
51+
Note that the LLVM Coding Standards have a golden rule:
52+
53+
> **If you are extending, enhancing, or bug fixing already implemented code, use the style that is already being used so that the source is uniform and easy to follow.**
54+
55+
The golden rule should continue to be applied to places where DXC is self-consistent. A good example is DXC's common use of `PascalCase` instead of `camelCase` for APIs in some parts of the HLSL implementation. In any place where DXC is not self-consistent new code should follow the LLVM Coding Standard.
56+
57+
A good secondary rule to follow is:
58+
59+
> **When in doubt, follow LLVM.**
60+
61+
Adopting LLVM's coding standards provides a consistent set of rules and guidelines to hold all contributions to. This allows patch authors to clearly understand the expectations placed on contributions, and allows reviewers to have a bar to measure contributions against. Aligning with LLVM by default ensures the path of least resistance for everyone.
62+
63+
Since many of the LLVM Coding Standards are not enforced automatically we rely on code reviews to provide feedback and ensure contributions align with the expected coding standards. Since we rely on reviewers for enforcement and humans make mistakes, please keep in mind:
64+
65+
> **Code review is a conversation.**
66+
67+
It is completely reasonable for a patch author to question feedback and provide additional context about why something was done the way it was. Reviewers often see narrow slices in diffs rather than the full context of a file or part of the compiler, so they may not always provide perfect feedback. This is especially true with the application of the "golden rule" since it depends on understanding a wider context.
68+
4769
### Documenting Pull Requests
4870

4971
Pull request descriptions should have the following format:

0 commit comments

Comments
 (0)