Skip to content

Commit d834a30

Browse files
hvdijkhvdijk
authored
Merge pull request #669 from hvdijk/rfcs-2-more-detail
RFC 2: Include more detail on how to write RFCs.
2 parents b06e230 + 4403ef8 commit d834a30

File tree

4 files changed

+127
-50
lines changed

4 files changed

+127
-50
lines changed

‎rfc-0000.md

+3
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,14 @@ represent their historical record.
3131
</thead>
3232
<tbody>
3333
{% for page in site.html_pages %}
34+
{% assign split = page.url | split: '/' %}
35+
{% if split.size == 2 %}
3436
<tr>
3537
<td>{{ page.rfc }}</td>
3638
<td><a href="{{ page.url | prepend:site.baseurl }}">{{ page.title }}</a></td>
3739
<td>{{ page.author }}</td>
3840
</tr>
41+
{% endif %}
3942
{% endfor %}
4043
</tbody>
4144
</table>

‎rfc-0001.md

+8-5
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
rfc: 1
33
title: RFC Purpose and Guidelines
44
author: Harald van Dijk <[email protected]>
5-
date: 2024-12-06
5+
status: active
66
---
77

88
<details markdown="1">
@@ -59,8 +59,9 @@ Each RFC must have a champion -- someone who writes the RFC using the style and
5959
format described below, shepherds the discussions in the appropriate forums, and
6060
attempts to build community consensus around the idea. The RFC champion (a.k.a.
6161
author) should first attempt to ascertain whether the idea is RFC-able. Posting
62-
to [oneAPI Construction Kit Discussions][ock-discussions] is usually the best
63-
way to go about this, unless a more specialized venue is appropriate.
62+
to the [Ideas category][ock-discussions-ideas] of [oneAPI Construction Kit
63+
Discussions][ock-discussions] is usually the best way to go about this, unless a
64+
more specialized venue is appropriate.
6465

6566
Vetting an idea publicly before going as far as writing an RFC is meant to save
6667
the potential author time. Asking the community first if an idea is original
@@ -164,8 +165,8 @@ the discussion, so long as the the following criteria are met:
164165
- A direct link to the current discussion thread is provided in the RFC under
165166
the `discussions-to` header.
166167

167-
The [oneAPI Construction Kit Discussions][ock-discussions] is the preferred
168-
choice for most RFCs.
168+
The [RFCs category][ock-discussions-rfcs] of [oneAPI Construction Kit
169+
Discussions][ock-discussions] is the preferred choice for most RFCs.
169170

170171
If an RFC undergoes a significant re-write or other major, substantive changes
171172
to its proposed specification, a new thread should typically be created in the
@@ -440,6 +441,8 @@ editorial part (which is generally a low volume task).
440441
[ock-clang-format]: https://github.com/uxlfoundation/oneapi-construction-kit/blob/main/.clang-format
441442
[ock-coc]: https://github.com/uxlfoundation/oneapi-construction-kit/blob/main/CODE_OF_CONDUCT.md
442443
[ock-discussions]: https://github.com/uxlfoundation/oneapi-construction-kit/discussions
444+
[ock-discussions-ideas]: https://github.com/uxlfoundation/oneapi-construction-kit/discussions/categories/ideas
445+
[ock-discussions-rfcs]: https://github.com/uxlfoundation/oneapi-construction-kit/discussions/categories/rfcs
443446
[ock-issues]: https://github.com/uxlfoundation/oneapi-construction-kit/issues
444447
[ock-pulls]: https://github.com/uxlfoundation/oneapi-construction-kit/pulls
445448
[ock-rfcs]: https://github.com/uxlfoundation/oneapi-construction-kit/tree/rfcs

‎rfc-0002.md

+53-45
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,7 @@
22
rfc: 2
33
title: RFC template
44
author: Harald van Dijk <[email protected]>
5-
status: draft
6-
---
7-
8-
``` text
9-
---
10-
rfc: <REQUIRED: RFC number>
11-
title: <REQUIRED: RFC title>
12-
author: <REQUIRED: list of authors' names and optionally, email addresses>
13-
sponsor: <name of sponsor>
14-
status: <REQUIRED: draft | active | accepted | rejected | withdrawn | final>
5+
status: active
156
---
167

178
<details markdown="1">
@@ -22,50 +13,67 @@ status: <REQUIRED: draft | active | accepted | rejected | withdrawn | final>
2213

2314
# Abstract
2415

25-
[A short (~200 word) description of the technical issue being addressed.]
16+
This RFC provides a boilerplate or sample template for creating your own
17+
Markdown RFCs. In conjunction with the content guidelines in
18+
[RFC 1][rfc-0001], this should make it easy for you to conform your own RFCs
19+
to the format outlined below.
2620

27-
# Motivation
21+
Note: if you are reading this RFC via the web, you should first grab the textr
22+
(Markdown) source of this RFC in order to complete the steps below. DO NOT USE
23+
THE HTML FILE AS YOUR TEMPLATE!
2824

29-
[Clearly explain why the existing language specification is inadequate to address the problem that the RFC solves.]
25+
The source for this (or any) RFC can be found in the [`rfcs` branch of the
26+
oneAPI Construction Kit repository][ock-rfcs].
3027

3128
# Rationale
3229

33-
[Describe why particular design decisions were made.]
34-
35-
# Specification
36-
37-
[Describe the syntax and semantics of any new language feature.]
38-
39-
# Backwards Compatibility
40-
41-
[Describe potential impact and severity on pre-existing code.]
42-
43-
# Security Implications
44-
45-
[How could a malicious user take advantage of this new feature?]
46-
47-
# How to Teach This
30+
If you intend to submit a RFC, you MUST use this template, in conjunction with
31+
the format guidelines below, to ensure that your RFC submission won't get
32+
automatically rejected because of form.
33+
34+
Markdown provides PEP authors with useful functionality and expressivity, while
35+
maintaining easy readability in the source text. The processed HTML form makes
36+
the functionality accessible to readers: live hyperlinks, styled text, tables,
37+
images, and automatic tables of contents, among other advantages.
38+
39+
# How to Use This Template
40+
41+
- Make a copy of [`rfc-0002/rfc-NNNN.md`][rfc-nnnn] (the `.md` file, **not** the
42+
HTML!) and perform the following edits. Name the new file `rfc-NNNN.md`, using
43+
the next available number (not used by a published or in-PR RFC).
44+
- Replace the "rfc" header with "rfc: NNNN", matching the file name. Note that
45+
the file name should be padded with zeros (eg `rfc-0002.md`), but the header
46+
should not (`rfc: 2`).
47+
- Change the title header to the title of your RFC.
48+
- Change the author header to include your name, and optionally your email
49+
address. Be sure to follow the format carefully: your name must appear first,
50+
and it must not be contained in parentheses. Your email address may appear
51+
second (or it can be omitted) and if it appears, it must appear in angle
52+
brackets. It is okay to obfuscate your email address.
53+
- If none of the authors are core developers, include a Sponsor header with the
54+
name of the core developer sponsoring your RFC.
55+
- Add the direct URL of the RFC's canonical discussion thread (on e.g. GitHub
56+
Discussions) under the discussions-to header. If the thread will be created
57+
after the RFC is submitted as an official draft, it is okay to just list the
58+
venue name initially, but remember to update the RFC with the URL as soon as
59+
the RFC is successfully merged to the `rfcs` branch and you create the
60+
corresponding discussion thread. See [RFC 1][rfc-0001] for more details.
61+
- Change the status header to "draft".
62+
- Now write your Abstract, Rationale, and other content for your RFC, replacing
63+
placeholders with your own text.
64+
- Update your Footnotes section, listing any footnotes and non-inline link
65+
targets referenced by the text.
66+
- Create a pull request against the [`rfcs` branch][ock-rfcs].
4867

49-
[How to teach users, new and experienced, how to apply the RFC to their work.]
50-
51-
# Reference Implementation
52-
53-
[Link to any existing implementation and details about its state, e.g. proof-of-concept.]
54-
55-
# Rejected Ideas
56-
57-
[Why certain ideas that were brought while discussing this RFC were not ultimately pursued.]
58-
59-
# Open Issues
60-
61-
[Any points that are still being decided/discussed.]
62-
63-
# Footnotes
68+
``` text
69+
{% include_relative rfc-0002/rfc-NNNN.md %}
70+
```
6471

65-
[A collection of footnotes cited in the RFC, and a place to list non-inline hyperlink targets.]
72+
[ock-rfcs]: https://github.com/uxlfoundation/oneapi-construction-kit/tree/rfcs
73+
[rfc-0001]: rfc-0001.md
74+
[rfc-nnnn]: https://github.com/uxlfoundation/oneapi-construction-kit/blob/rfcs/rfc-0002/rfc-NNNN.md
6675

6776
# Copyright
6877

6978
This document is placed in the public domain or under the
7079
CC0-1.0-Universal license, whichever is more permissive.
71-
```

‎rfc-0002/rfc-NNNN.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
rfc: <REQUIRED - RFC number>
3+
title: <REQUIRED - RFC title>
4+
author: <REQUIRED - list of authors' names and optionally, email addresses>
5+
sponsor: <OPTIONAL - name of sponsor, remove if not applicable>
6+
discussions-to: <REQUIRED - URL of current canonical discussion thread>
7+
status: <REQUIRED - draft | active | accepted | rejected | withdrawn | final>
8+
---
9+
10+
<details markdown="1">
11+
<summary>Table of Contents</summary>
12+
* Table of Contents
13+
{:toc}
14+
</details>
15+
16+
# Abstract
17+
18+
[A short (~200 word) description of the technical issue being addressed.]
19+
20+
# Motivation
21+
22+
[Clearly explain why the existing language specification is inadequate to address the problem that the RFC solves.]
23+
24+
# Rationale
25+
26+
[Describe why particular design decisions were made.]
27+
28+
# Specification
29+
30+
[Describe the syntax and semantics of any new language feature.]
31+
32+
# Backwards Compatibility
33+
34+
[Describe potential impact and severity on pre-existing code.]
35+
36+
# Security Implications
37+
38+
[How could a malicious user take advantage of this new feature?]
39+
40+
# How to Teach This
41+
42+
[How to teach users, new and experienced, how to apply the RFC to their work.]
43+
44+
# Reference Implementation
45+
46+
[Link to any existing implementation and details about its state, e.g. proof-of-concept.]
47+
48+
# Rejected Ideas
49+
50+
[Why certain ideas that were brought while discussing this RFC were not ultimately pursued.]
51+
52+
# Open Issues
53+
54+
[Any points that are still being decided/discussed.]
55+
56+
# Footnotes
57+
58+
[A collection of footnotes cited in the RFC, and a place to list non-inline hyperlink targets.]
59+
60+
# Copyright
61+
62+
This document is placed in the public domain or under the
63+
CC0-1.0-Universal license, whichever is more permissive.

0 commit comments

Comments
 (0)