UP | HOME

SDML RFC Process

Table of Contents

Given an RFC titled “Example New RFC”;

  1. Determine the next RFC number (3 digits, 0 padded,as nnn) from the index.org file.
  2. Create a new document nnn-example-new-rfc.org using the template at the end of this document.
  3. Any additional files such as images must start with the same nnn- prefix.
  4. Add a new section to the index.org file with the block of code below.
  5. Create a new pull request with these changes and label as “RFC”.

1. RFC Document States

An RFC document goes through a number of different lifecycle states from Draft to Approved, Rejected, or Withdrawn. Each of these states is the name of an org-mode TODO state in the index file and as such appears in all upper-case as the first word of the section title.

sdml-rfc-states.svg

Figure 1: RFC State Machines

Draft
All documents are created in a Draft status, this allows for a round of informal comments before it is proposed. Draft documents may move to:
  • proposed for formal comments,
  • rejected if it is determined that it is invalid in some way, or
  • withdrawn if the author chooses to not move it forward.
Proposed
This document has been formally proposed and comments are solicited until it appears that some consensus has been reached. The document may then move to:
  • proposed if comments require some immediate edits,
  • testing if the comments require some more tests to show how the proposal works,
  • approved if all comments have been satisfied,
  • rejected if enough comments suggest the proposal is not valid or useful,
  • withdrawn if the author chooses to not move it forward.
Testing
Additional tests (by which we may mean actual test case text, code, or canvassing users) are being performed to provide more data to the document. The document may then move to:
  • proposed if testing is complete and the updated document goes back for comments,
  • withdrawn if the author chooses to not move it forward.
Updating
A previously approved document is undergoing revision (a new version perhaps) and this is used to show that while an existing approved version exists it will be replaced at some point. The document may then move to:
  • proposed if the update is expected to replace the existing approved version, this opens comments on the revised document,
  • accepts if the update is canceled; withdrawal of an update returns the document to its previous accepted state.
Approved
The RFC has been approved and any proposed changes have been accepted into the repository. The document may then move to:
  • updating if the current approved document requires an update,
  • withdrawn if the author chooses to deprecate the existing approved document.
Rejected
The RFC was rejected and no further action will be taken.
Withdrawn
The document is archived and no further action will be taken.

1.1. Impact Tags

The index also uses org-mode tags to identify the impact of an RFC. While a single tag is preferred multiple may be specified if it makes sense. When choosing a tag try and choose the tag that corresponds to the area of focus; for example, if the focus is to change the syntax to make it easier for the user to do something then the tag should be grammar even if the change also affects the semantics, and tests. If the purpose is to make a change in the semantics to clarify how the language behaves the tag should be semantics even if it requires a corresponding change in grammar.

The current tags are:

grammar
a change impacts the grammar itself, this generally implies changes to all of the below.
semantics
a change impacts the semantics, which may or may not adjust the grammar.
queries
a change impacts one of the scheme query files in the queries directory.
tests
a change impacts one of the tests (corpus or highlight) in the test directory.
examples
a change impacts one of the example files in the example directory.

2. RFC Index File

Copy this block to the index file and edit as appropriate. 

* DRAFT Example New RFC    :tag:
:PROPERTIES:
:NUMBER: nnn
:AUTHOR: Primary Author
:CREATED: <2023-12-07 Thu>
:END:
:LOGBOOK:
:END:

Current RFC Document

3. RFC File Template

The linked file (template.org) is a good base for a new RFC. Note that the italic text in green below is placeholder text and should all be replaced with your content. 

#+TITLE: RFCnnn: Title of Document
#+SUBTITLE: Status: Draft
#+AUTHOR: Primary Author
#+EMAIL: primary@example.com
#+LANGUAGE: en
#+OPTIONS: author:nil created:nil creator:nil date:nil email:nil toc:t
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="../plain-sdml.css"/>
#+HTML_LINK_HOME: ./index.html
#+HTML_LINK_UP: ./index.html

* Introduction

Brief, 2-3 sentence, description of this RFC.

Contributors

This section is optional, but must exist if there is more than one
author/contributor.

Document Status History

| Date         | Status | Comment | Grammar Version |
|--------------+--------+---------+-----------------|
| [2023-12-07] | Draft  |         | 0.2.6           |

In the table above, the date should be the date of the pull request that
publishes the initial draft. The Grammar version is the version that this
document used as a basis for any changes or references.

* Motivation

Why is there a problem, or a potential opportunity. Please include examples.

* Alternatives Considered

This is a good way to describe the thinking behind the proposed change or
changes.

* Proposed Change

The following changes are required:

What are you proposing to change?

** Test cases

What test cases do you intend to include.

** Impact

What is the scope of the impact, this should relate to any tags you
added to the section in the index file.

Created: 2023-12-21 Thu 11:46