Skip to content

Commit 51e4567

Browse files
jvepsalainen-nvjvepsalainen-nv
authored
Merge branch 'master' into fix/coverage-demo-dll-search-and-ascii-output
2 parents 9db4d6e + 2a6b086 commit 51e4567

2 files changed

Lines changed: 158 additions & 0 deletions

File tree

‎docs/language-reference/introduction-language-evolution.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Language Evolution
2+
3+
The Slang language evolution is driven by two processes:
4+
5+
- The specification proposal process.
6+
- GitHub issue-driven process.
7+
8+
The specification proposal process is intended for significant changes to the application-visible part of
9+
Slang, including its syntax and standard modules. For other changes, a lighter-weight GitHub issue-driven
10+
process may be used.
11+
12+
When the following criteria are met, the specification proposal process should be used:
13+
14+
1. The change applies to the application-visible part of Slang. That is, syntax (grammar and the underlying
15+
semantics) or stable Slang standard modules; AND
16+
2. The change is not a minor defect fix; AND
17+
3. The change does not reflect changes in the downstream languages in an obvious way; AND
18+
4. Any of the following applies:
19+
1. The change adds new syntax for Slang applications; OR
20+
2. The change adds new items in stable Slang standard modules; OR
21+
3. Existing syntax for Slang applications is modified; OR
22+
4. Existing syntax for Slang applications is deprecated; OR
23+
5. Existing standard modules for Slang applications are modified (see Remark 2 below); OR
24+
6. Existing standard modules for Slang applications are deprecated; OR
25+
7. An experimental Slang standard module is matured as stable; OR
26+
8. A stable Slang standard module is deprecated or its status is reverted to experimental; OR
27+
9. The change removes support for a Slang language version.
28+
29+
A change is considered a minor defect fix when:
30+
31+
1. it fixes an obvious defect; OR
32+
2. it clarifies existing and previously undocumented behavior.
33+
34+
The specification proposal process may also be used when the above criteria are not met. In particular, the
35+
proposal process is recommended for experimental features that are expected to be integrated into Slang. The
36+
proposal process is explicitly not required for internal Slang language features such as compiler intrinsics.
37+
38+
**Criteria interpretation examples:**
39+
40+
<table>
41+
<tr>
42+
<th>Item</th><th>Process</th><th>Rationale</th>
43+
</tr>
44+
<tr>
45+
<td><a href="https://github.com/shader-slang/spec/blob/main/proposals/027-tuple-syntax.md">Tuple syntax (2026)</a></td>
46+
<td>Spec proposal</td>
47+
<td>New syntax to application-visible Slang, and existing syntax is modified.</td>
48+
</tr>
49+
<tr>
50+
<td><a href="https://github.com/shader-slang/spec/blob/main/proposals/020-stage-switch.md"><code>stage_switch</code></a></td>
51+
<td>Spec proposal</td>
52+
<td>New syntax to application-visible Slang (language construct).</td>
53+
</tr>
54+
<tr>
55+
<td><a href="https://github.com/shader-slang/slang/issues/11175">Deprecation of unscoped enumerations</a></td>
56+
<td>Spec proposal</td>
57+
<td>Deprecation and scheduled removal of existing syntax.</td>
58+
</tr>
59+
<tr>
60+
<td><a href="https://github.com/shader-slang/slang/issues/11216">Integer literal corner cases</a></td>
61+
<td>GitHub</td>
62+
<td>Clarification of previously undocumented corner cases.</td>
63+
</tr>
64+
<tr>
65+
<td><a href="https://github.com/shader-slang/slang/issues/11349">Fixing ambiguous generic application syntax</a></td>
66+
<td>GitHub</td>
67+
<td>Clarification of previously ambiguous grammatical rules.</td>
68+
</tr>
69+
<tr>
70+
<td><a href="https://github.com/shader-slang/slang/issues/11276">Fix handling of floating point literals</a></td>
71+
<td>GitHub</td>
72+
<td>Clarification of previously undocumented corner cases, and correction of obviously wrong existing behavior
73+
in the compiler.</td>
74+
</tr>
75+
<tr>
76+
<td><a href="https://github.com/shader-slang/slang/issues/11156">Fix GL_EXT_texture_shadow_lod capability requirements in depth sampling (GLSL)</a></td>
77+
<td>GitHub</td>
78+
<td>Adjust standard module behavior to better fit the downstream language.</td>
79+
</tr>
80+
<tr>
81+
<td>Changes to <code>__intrinsic_type</code> keyword</td>
82+
<td>GitHub</td>
83+
<td>The <code>__intrinsic_type</code> keyword is an implementation-specific language extension that is internal to the
84+
Slang compiler. It should never be used directly by an application.</td>
85+
</tr>
86+
</table>
87+
88+
> 📝 **Remark 1:** The specification proposal process is significantly heavier than the GitHub
89+
> issue-driven process. This is the reason why fixing minor defects is exempted from the language
90+
> specification proposal process, even if the fixes are potentially breaking changes.
91+
92+
> 📝 **Remark 2:** The change process for Slang standard modules is still under consideration. This is tracked
93+
> by GitHub issue <a href="https://github.com/shader-slang/slang/issues/11612">#11612</a>.
94+
95+
## Specification Proposal Process
96+
97+
The specification proposal process begins with the submission of a proposal formatted according to the
98+
<a href="https://github.com/shader-slang/spec/blob/main/proposals/000-template.md">proposal template</a>. The proposal is
99+
then reviewed, and if approved, scheduled for implementation. The proposals are public, allowing for community
100+
feedback.
101+
102+
When a proposal does not contain backward breaking changes, it may be implemented for all Slang language
103+
versions.
104+
105+
When a proposal contains backward breaking changes, then:
106+
107+
1. The target Slang language version should be identified. This may be the language version currently being
108+
developed or a future language version.
109+
2. When the proposal is implemented:
110+
1. The `slangc` compiler should select either the legacy or the new behavior according to the `-std`
111+
command-line switch or the `#language` directive.
112+
2. When legacy behavior is selected, the `slangc` compiler should emit warning diagnostics to ensure that
113+
users get notified on breaking changes in advance. There should be pointers to migration steps.
114+
3. When new behavior is selected, the `slangc` compiler is recommended to detect breaking legacy patterns
115+
when possible and point to migration steps.
116+
117+
**Example:**
118+
119+
*Unscoped enumerations* have been slated for removal, tracked by GitHub issue
120+
#[11175](https://github.com/shader-slang/slang/issues/11175). This is a potentially significant breaking
121+
change that requires following the specification proposal process.
122+
123+
Tentatively, the unscoped enumerations are going to be removed in Slang 2028. The current default language is 2025 at
124+
the time of writing. The next steps:
125+
126+
1. Write a language specification proposal.
127+
2. After the proposal has been reviewed and accepted, implement the diagnostics warning in `slangc` when
128+
unscoped enumerations are used. The diagnostic warning should state that unscoped enumerations are a
129+
deprecated feature, expected to be removed in Slang 2028. A suggestion to migrate to scoped enumerations
130+
should be included in diagnostics.
131+
- The diagnostic warning is included for all Slang language versions prior to 2028.
132+
3. When Slang 2028 (or later) is selected, `slangc` shall trigger an error if unscoped enumerations are
133+
attempted to be used.
134+
4. When support for all language versions prior to Slang 2028 is removed from `slangc`, all code related to
135+
unscoped enumerations may be removed from the compiler.
136+
137+
## GitHub Process
138+
139+
The GitHub process is straightforward: file a GitHub issue with "Language Maturity" issue type, and submit a
140+
pull request. See GitHub issue #[11216](https://github.com/shader-slang/slang/issues/11216) for an example.
141+
142+
## Checklist for Implementing Changes Related to Slang Language
143+
144+
1. Implement the feature.
145+
- For a staged syntax change, use the language version to select the behavior. See
146+
https://github.com/shader-slang/slang/blob/fbf41e87a3493bfe4417b3b3a92c814dde391960/source/slang/slang-parser.cpp#L5907
147+
for an example.
148+
- For a staged standard module change, use attributes
149+
[\[deprecated\]](../../../core-module-reference/attributes/deprecated.html) and
150+
[\[RemovedSince\]](../../../core-module-reference/attributes/removedsince-07.html) to mark declarations
151+
deprecated and removed.
152+
2. Implement tests.
153+
- For language-version-dependent behavior changes, include before/after testing.
154+
3. Update [Slang User's Guide](https://github.com/shader-slang/slang/tree/master/docs/user-guide).
155+
4. Update [Slang Language Reference Manual](https://github.com/shader-slang/slang/tree/master/docs/language-reference).
156+
5. Update [Slang Examples](https://github.com/shader-slang/slang/tree/master/examples) if appropriate.
157+
6. If the specification proposal process is used, mark the related specification proposal implemented.

‎docs/language-reference/introduction.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ performance-oriented GPU programming for real-time graphics.
1010

1111
* [Language Goals (TODO)](introduction-goals.md)
1212
* [Typographical Conventions](introduction-typographical-conventions.md)
13+
* [Language Evolution](introduction-language-evolution.md)
1314

1415

1516
## Purpose of this document

0 commit comments

Comments
 (0)