You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
One of the easiest ways to contribute is to participate in discussions and discuss issues. You can also contribute by submitting pull requests with code changes.
4
4
5
-
6
5
## General feedback and discussions?
7
-
Please start a discussion on the repo issue tracker.
8
6
7
+
Please start a discussion on the repo issue tracker.
9
8
10
9
## Bugs and feature requests?
11
-
For non-security related bugs please log a new issue in the GitHub repo.
12
10
11
+
For non-security related bugs please log a new issue in the GitHub repo.
13
12
14
13
## Reporting security issues and bugs
15
-
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/ff852094.aspx).
16
14
15
+
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <[email protected]>. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/ff852094.aspx).
17
16
18
17
## Filing issues
18
+
19
19
When filing issues, please use our [bug filing templates](https://github.com/aspnet/Home/wiki/Functional-bug-template).
20
20
The best way to get your bug fixed is to be as detailed as you can be about the problem.
21
21
Providing a minimal project with steps to reproduce the problem is ideal.
@@ -28,65 +28,116 @@ Here are questions you can answer before you file a bug to make sure you're not
28
28
29
29
GitHub supports [markdown](https://help.github.com/articles/github-flavored-markdown/), so when filing bugs make sure you check the formatting before clicking submit.
30
30
31
-
32
31
## Contributing code and content
32
+
33
33
You will need to complete a Contributor License Agreement (CLA) before your pull request can be accepted. This agreement testifies that you are granting us permission to use the source code you are submitting, and that this work is being submitted under appropriate license that we can use it.
34
34
35
35
You can complete the CLA by going through the steps at the [Contribution License Agreement site](https://cla.microsoft.com). Once we have received the signed CLA, we'll review the request. You will only need to do this once.
36
36
37
-
Make sure you can build the code. Familiarize yourself with the project workflow and our coding conventions. If you don't know what a pull request is read this article: https://help.github.com/articles/using-pull-requests. The hcttest command is your friend.
37
+
Make sure you can build the code. Familiarize yourself with the project workflow and our coding conventions. If you don't know what a pull request is read this article: <https://help.github.com/articles/using-pull-requests>.
38
38
39
39
Before submitting a feature or substantial code contribution please discuss it with the team and ensure it follows the product roadmap. You might also read these two blogs posts on contributing code: [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html) by Miguel de Icaza and [Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/) by Ilya Grigorik. Note that all code submissions will be rigorously reviewed and tested by the team, and only those that meet an extremely high bar for both quality and design/roadmap appropriateness will be merged into the source.
40
40
41
-
Here's a few things you should always do when making changes to the code base:
42
-
43
-
**Engineering guidelines**
41
+
### Coding guidelines
44
42
45
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.
46
44
47
-
DXC has adopted a clang-format requirement for all incoming changes. 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.
45
+
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.
48
46
49
-
**Commit/Pull Request Format**
47
+
### Documenting Pull Requests
50
48
51
-
```
52
-
Summary of the changes (Less than 80 chars)
53
-
- Detail 1
54
-
- Detail 2
49
+
Pull request descriptions should have the following format:
50
+
51
+
```md
52
+
Title summary of the changes (Less than 80 chars)
53
+
- Description Detail 1
54
+
- Description Detail 2
55
55
56
-
Fixes #bugnumber (in this specific format)
56
+
Fixes #bugnumber (Where relevant. In this specific format)
57
57
```
58
58
59
-
Your pull request should:
60
-
61
-
* Include a description of what your change intends to do
62
-
* The title of your PR should be a very brief description of the change, and
63
-
can use tags to allow for speedy categorization.
64
-
* Titles under 76 characters print nicely in unix terminals under `git log`.
65
-
This is not a hard requirement, but is good guidance.
66
-
* Title tags are generally one word or acronym enclosed in square brackets.
67
-
Limiting to one or two tags is ideal to keep titles short. Some examples
68
-
of common tags are:
69
-
*[NFC] - No Functional Change
70
-
*[RFC] - Request For Comments (often used for drafts to get feedback)
71
-
*[Doc] - Documentation change
72
-
*[SPIRV] - Changes related to SPIR-V
73
-
*[HLSL2021] - Changes related to HLSL 2021 features
74
-
* Other tags in use: [Linux], [mac], [Win], [PIX], etc...
75
-
* Tags aren't formalized or any specific limited set. If you're unsure of
76
-
a reasonable tag to use, just don't use any. If you want to invent a new
77
-
tag, go for it! These are to help categorize changes at a glance.
78
-
* The PR description should include a more detailed description of the change,
79
-
an explanation for the motivation of the change, and links to any relevant
80
-
Issues. This does not need to be a dissertation, but should leave
81
-
breadcrumbs for the next person debugging your code (who might be you).
82
-
* Using the words `Fixes`, `Fixed`, `Closes`, `Closed`, or `Close` followed by
83
-
`#<issuenumber>`, will auto close an issue after the PR is merged.
84
-
* Be a child commit of a reasonably recent commit in the main branch
85
-
* Pass all unit tests
86
-
* Ensure that the title and description are fully up to date before merging
87
-
* The title and description feed the final git commit message, and we want to
88
-
ensure high quality commit messages in the repository history.
89
-
* Include adequate tests
90
-
* At least one test should fail in the absence of your non-test code changes. If your PR does not match this criteria, please specify why
91
-
* Tests should include reasonable permutations of the target fix/change
92
-
* Include baseline changes with your change as needed
59
+
#### Titles
60
+
61
+
The title should focus on what the change intends to do rather than how it was done.
62
+
The description can and should explain how it was done if not obvious.
63
+
64
+
Titles under 76 characters print nicely in unix terminals under `git log`.
65
+
This is not a hard requirement, but is good guidance.
66
+
67
+
Tags in titles allow for speedy categorization
68
+
Title tags are generally one word or acronym enclosed in square brackets.
69
+
Limiting to one or two tags is ideal to keep titles short.
70
+
Some examples of common tags are:
71
+
72
+
-`[NFC]` - No Functional Change
73
+
-`[RFC]` - Request For Comments (often used for drafts to get feedback)
74
+
-`[Doc]` - Documentation change
75
+
-`[SPIRV]` - Changes related to SPIR-V
76
+
-`[HLSL2021]` - Changes related to HLSL 2021 features
77
+
- Other tags in use: `[Linux]`, `[mac]`, `[Win]`, `[PIX]`, etc...
78
+
79
+
Tags aren't formalized or any specific limited set.
80
+
If you're unsure of a reasonable tag to use, just don't use any.
81
+
If you want to invent a new tag, go for it!
82
+
These are to help categorize changes at a glance.
83
+
84
+
#### Descriptions
85
+
86
+
The PR description should include a more detailed description of the change,
87
+
an explanation for the motivation of the change, and links to any relevant Issues.
88
+
This does not need to be a dissertation, but should leave breadcrumbs for the next person debugging your code (who might be you).
89
+
90
+
Using the words `Fixes`, `Fixed`, `Closes`, `Closed`, or `Close` followed by
91
+
`#<issuenumber>`, will auto close an issue after the PR is merged.
92
+
93
+
#### Release Notes
94
+
95
+
Significant changes may require release notes that highlight important
96
+
compiler behavior changes for each named release.
97
+
These include changes that are:
98
+
99
+
- Visible to the users
100
+
- Significant changes to compiler behavior
101
+
- New features: Language, Hardware support, compiler options
102
+
- Important bug fixes
103
+
- Changes in default behavior
104
+
105
+
When such a change is made, the release note should be included as part of that change.
106
+
This is done in the docs/ReleaseNotes.md file.
107
+
108
+
If the change is meant for a named release, it should be added to that named release's section of the release notes file.
109
+
As the change is merged to the appropriate release branches, the release notes will come along with it.
110
+
111
+
If a change is meant for the next upcoming release, it should be added to the "Upcoming Release" section.
112
+
When the next upcoming release is named, the title will be updated and the release note will be included in the appropriate release.
113
+
114
+
When writing release note list entries:
115
+
116
+
- Keep the description to a single sentence.
117
+
- Links to specific PRs shouldn't be included.
118
+
- Markdown links to bugs are encouraged if the issue is too complicated to completely explain in a single sentence.
119
+
- Remember to update release notes as the nature of the change alters or is removed.
120
+
121
+
### Testing Pull Requests
122
+
123
+
All changes that make functional or behavioral changes to the compiler whether by fixing bugs or adding features
124
+
must include additional testing in the implementing pull request.
125
+
Changes that do not change behavior may still be required to add testing if the change impacts areas with limited test coverage
126
+
to verify that the change doesn't alter previously untested, but important behavior.
127
+
For bug fixes, at least one added test should fail in the absence of your non-test code changes.
128
+
Tests should include reasonable permutations of the target fix/change.
129
+
Include baseline changes with your change as needed.
130
+
131
+
Submitting a pull request kicks off an automated set of regression tests that verify the change introduces no unwanted changes in behavior.
132
+
For a pull request to be mergeable in GitHub, it will have to pass this regression test suite.
133
+
Changes made to DXC for the benefit of external projects should be verified using that project's testing protocols to avoid churn.
134
+
135
+
For cases where any of the above testing requirements are not possible, please specify why in the pull request.
136
+
137
+
### Merging Pull Requests
138
+
139
+
Pull requests should be a child commit of a reasonably recent commit in the main branch.
140
+
A pull request's commits should be squashed on merging except in very special circumstances usually involving release branches.
141
+
142
+
Ensure that the title and description are fully up to date before merging.
143
+
The title and description feed the final git commit message, and we want to ensure high quality commit messages in the repository history.
0 commit comments