Skip to content

Latest commit

 

History

History
108 lines (76 loc) · 5.27 KB

rigolo-0001.adoc

File metadata and controls

108 lines (76 loc) · 5.27 KB
Raw

RiGolo Purpose and Guidelines

RiGolo

1

Title

RiGolo Purpose and Guidelines

Author

Yannick Loiseau

Status

Draft

Type

Process

Created

2016-10-01

Abstract

This document describe the rationale for the Request for Improvement of Golo, as well as the associated workflow. It is heavily inspired by python’s PEP 1.

What is a RiGolo?

A RiGolo is a Request for Improvement of Golo. It’s a design document describing a new Golo feature, a protocol, or a standardized API. The RiGolo should provide a concise technical specification, as well as a rationale and motivation.

The main purpose of the RiGolo is to collect community input and document the design decisions. The author is responsible for building consensus within the community and documenting dissenting opinions, which could be lost if Golo ever changes its hosting platform.

Because the RiGolos are maintained in a versioned repository, their revision history is the historical record of the proposal.

RiGolo Workflow

Golo BDFL

This acronym stands for “Benevolent Dictator for Life” and refers to Julien Ponge @jponge, the original creator of, and the final design authority for, the Golo programming language.

RiGolo or Issue?

It is highly recommended that a RiGolo contain a single key proposal or new idea. Small enhancements or patches often don’t need a RiGolo and can be proposed by opening an issue in the golo-lang issue tracker or by directly opening a pull request for discussion.

The more focused the RiGolo, the more successful it tends to be. If in doubt, split your RiGolo into several well-focused ones.

Submitting a RiGolo

Each RiGolo must have a main author responsible for building community consensus around the idea. The main author should also determine whether the idea deserve a RiGolo or not. Starting a preliminary issue in the tracker or posting a message on the golo-dev mailing list are the best way to go about this. Asking the Golo community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions. It also helps to make sure the idea is applicable to the entire community and not just the author.

According to this first feedback, a draft RiGolo will be proposed as a pull request on the golo-lang/rigolo repository. This draft must take the form of a new file in the RiGolo directory, in its own branch, with the format and style described bellow, and a “Draft” status.

RiGolo Review & Resolution

The draft can thus be discussed further in the pull request comments, and changes can be done by pushing new commits to the pull request. It is the responsibility of the main author to keep the draft up to date with the feedback from discussions and reviews.

If no consensus can be reach, the BDFL will decide.

When the draft reaches a satisfactory state, a RiGolo number is given, the status changed to “Accepted” and the pull request can be merged. For a RiGolo to be accepted it must be a clear and complete description of the proposed improvement. It must moreover comply with the Golo philosophy, which is whatever is acceptable by the BDFL.

A RiGolo can also be “Rejected”. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. The document is thus given a “Rejected” status, and the pull request is merge, to keep the information discussed. A section must be added to explain why the proposal was rejected.

RiGolo Formats and Structure

A RiGolo is a file in the asciidoc format. Only this “rich text” format is allowed for consistency, since it has more features and is a more manageable format than current alternatives. Each RiGolo should have the following parts:

  • Preamble: definition list containing meta-data, including the RiGolo number, a short descriptive title, the names, and optionally the contact info for each author, etc.

  • Abstract: a short description of the proposal.

  • Specification: The technical specification should describe the syntax and semantics of any new language feature. The specification should be detailed enough to allow competing, interoperable implementations.

  • Motivation: The motivation is critical for RiGolos that want to change the Golo language. It should clearly explain why the existing language specification is inadequate to address the problem that the RiGolo solves.

  • Rationale: The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

  • Backwards Compatibility: All RiGolos that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The proposal must explain how the author proposes to deal with these incompatibilities.