Whiley RFCs
Substantial change proposals for the Whiley language must be first
written up as an RFC and before they can be accepted. The Request for
Comment (RFC) process is intended to provide a peer review and voting
process to ensure change proposals are vetted and accepted by the
community.
When is an RFC needed?
The RFC process should be followed for all "substantial" changes to
the Whiley language. What exactly constitutes a "substantial" change
to the language is somewhat subtle (and subjective). For example, the
following changes would not be considered as substantial:
- Fixes for known bugs in the language (as identified by an
issue). A bug typically represents a situation where the
implementation of the language differs from the language
specification. In the normal course of events, one would first
raise an issue regarding the bug in question.
- Minor fixes for or improvements to the documentation of a source
file. Such changes can likely be accepted as pull requests
without issues being raised.
- Refactoring of an existing code base (e.g. the Whiley Compiler)
without otherwise changing the semantics or syntax of the
language. Whilst such refactorings can be substantial in nature,
they should not affect existing code. However, of course, in
practice such changes must be made in small incremental steps.
In contrast, the following changes would be considered as
substantial:
- Changes to the syntax of the language. This includes the addition
of new syntax, the removal of existing syntax and/or the replacement
of existing syntax. This is important because existing code may no
longer compiler after the change.
- Changes to the manner in which Whiley source files are accepted (or
not) by the compiler. For example, the introduction of a new type
checking phase, or the modification of an existing phase
(e.g. definite assignment). This is important because existing code
may no longer compiler after the change.
- Changes to the manner in which compiler Whiley code interfaces with
external code (i.e. the Foreign Function Interface). This is
important as such a change will affect existing code in a
potentially non-trivial fashion.
If in doubt regarding whether a change in substantial or not, one can
first raise this as an issue on the repository of the respective
component. Maintainers of that repository will then provide feedback
as to whether this requires an RFC or not.
The Process
To get a substantial change accepted into the Whiley language, one
must first get the corresponding RFC merged into this repository as a
markdown file. At this point the RFC is "active" and may be
implemented and, eventually, included in Whiley.
The process is as follows:
- Fork this RFC repository
- Copy
0000-template.md
to text/0000-my-feature.md
. Here,
my-feature
should be a descriptive name for the feature. Don't
assign an RFC number yet (since this may need to changed later
anyway)
- Complete the RFC by providing as many details of the proposal as
possible. The RFC must at a minimum: 1) motivate the need for the
change; 2) clearly explain the technical details of the change
(i.e. what parts of the language will be changed and in what way);
3) highlight any potential impacts of the change (esp. if the change
is not-backwards compatible); 4) consider alternative solutions to
the problem.
- Submit a Pull Request (PR) against this repository. This will
instigate the review period during which the RFC will receive
feedback and suggestions from the community.
- Update the RFC during the review period to address concerns or
issues raised during review. Such changes should be made as new
commits to the Pull Request, along with comments clarifying the
changes. RFCs are rarely accepted without changes.
- Acceptance. At some point, once the discussion has slowed, the
motion will be made for a decision to be made regarding the RFC
(often referred to as the Final Comment Period (FCP)). After a
short period (e.g. one week), the RFC will then either be accepted
(and merged) or rejected (and closed). In some cases, the RFC
maybe be postponed and kept open.
The Life-Cycle
Once an RFC has been accepted it must then be implemented. Observe
that, getting an RFC accepted does not automatically mean it will
become part of the Whiley language. The onus is on the authors and
supporters of the RFC to develop a suitable implementation. This will
then need to be merged into the relevant parts of the Whiley
ecosystem. This might include, for example, the Whiley Compiler (WyC)
and the Whiley Language Specification, etc.
Acknowledgements
Inspiration for this RFC process is taken from the processes used by
Pony and Rust.