Skip to content

RLN-IP 0002

RLN-IP: 2
Title: RLN-IP Process
Author: Anthony Culligan <anthony.culligan@setl.io>
Comments-Summary: No comments yet.
Comments-URI: https://github.com/
Status: Active
Type: Process
Created: 2023-11-02
License: CC-BY-SA-4.0: [Creative Commons Attribution-ShareAlike]

Abstract

An RLN Improvement Proposal (RLN-IP) is a design document providing imformation to RLN users, technology providers and other stakeholders describing a new feature for RLN, its processes or environment. The RLN-IP should provide a technical specification of the feature and rationale fo the feature.

It is intended that RLN-IPs be the primary way to propose new features and standards, for collecting stakeholder input on an issue, and for documenting design decisions that have gone into the RLN. The RLN-IP author is responsible for building consensus between stakeholders and fully documenting opinions and comments.

The RLN-IP repository will be maintained as a versioned repository and will be freely available and unpermissioned.

This RLN-IP is issued under the Creative Commons Attribution-Share Alike licence.

RLN-IP workflow

The process for an improvement proposal within a Regulated Liability Network (RLN) draws inspiration from similar improvement proposal processes while tailoring it to the unique regulatory and compliance considerations of the network. This RLN improvement proposal process begins with the identification of areas requiring enhancement. It could be triggered by regulatory updates, feedback from network participants, or internal assessments, ensuring alignment with the network's overarching mission and regulatory requirements.

After identifying an improvement area, a proposal is formally submitted by network participants or a designated group. This proposal undergoes an evaluation phase, where its feasibility, potential impact, and regulatory compliance are carefully assessed. Independent experts and regulatory authorities may be consulted to provide insights into the proposal's implications and adherence to the relevant regulations. The proposal may be modified, approved, or rejected based on this evaluation. Transparency and communication are maintained throughout this stage to keep stakeholders informed.

Upon approval of the proposal, the feature is allocated to an RLN release. Stakeholder involvement is crucial, as they play a pivotal role in executing the proposal. Implementation is acheived through technology providers complying with the RLN releases and publishing their compliance. Monitoring and reporting mechanisms are established to track progress and assess the impact of the changes. Ongoing feedback loops are maintained, and regular updates are provided to ensure that necessary adjustments can be made as the proposal is put into practice.

Each RLN-IP should have a sponsor and should have evidenced support by a number of RLN stakeholders

Vetting an idea publicly before going as far as writing an RLN-IP is meant to save both the potential author and the wider community time. Asking the RLN 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 (searching the internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where the RLN is used.

Once the champion has asked the RLN community as to whether an idea has any chance of acceptance, a draft RLN-IP should be presented to the RLN development mailing list. This gives the author a chance to flesh out the draft RLN-IP to make it properly formatted, of high quality, and to address additional concerns about the proposal. Following a discussion, the proposal should be submitted to the RLN-IP git repository as a pull request. This draft must be written in RLN-IP style as described below, and named with an alias such as "RLN-IP-johndoe-magicfeature" until an editor has assigned it an RLN-IP number (authors MUST NOT self-assign RLN-IP numbers).

RNL-IP authors are responsible for collecting community feedback on both the initial idea and the RLN-IP before submitting it for review. However, wherever possible, long open-ended discussions on public mailing lists should be avoided. Strategies to keep the discussions efficient include: setting up a separate SIG mailing list for the topic, having the RLN-IP author accept private comments in the early design phases, setting up a wiki page or git repository, etc. RLN-IP authors should use their discretion here.

It is highly recommended that a single RLN-IP contain a single key proposal or new idea. The more focused the RLN-IP, the more successful it tends to be. If in doubt, split your RLN-IP into several well-focused ones.

When the RLN-IP draft is complete, an RLN-IP editor will assign the RLN-IP a number, label it as Standards Track, Informational, or Process, and merge the pull request to the RLN-IP git repository. The RLN-IP editors will not unreasonably reject a RLN-IP. Reasons for rejecting RLN-IPs include duplication of effort, disregard for formatting rules, being too unfocused or too broad, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the RLN philosophy. For a RLN-IP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly.

The RLN-IP author may update the draft as necessary in the git repository. Updates to drafts should also be submitted by the author as pull requests.

Transferring RLN-IP Ownership

It occasionally becomes necessary to transfer ownership of RLN-IPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred RLN-IP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the RLN-IP process, or is unreachable or not responding to email.

If you are interested in assuming ownership of an RLN-IP, send a message asking to take over, addressed to both the original author and the RLN-IP editors. If the original author doesn't respond to email in a timely manner, the RLN-IP editors will make a unilateral decision (it's not like such decisions can't be reversed :).

RLN-IP Editors

The current RLN-IP editors are:

RLN-IP Editor Responsibilities & Workflow

The RLN-IP editors subscribe to the RLN-IP development mailing list. Off-list RLN-IP-related correspondence should be sent (or CC'd) to the RLN-IP editors.

For each new RLN-IP that comes in an editor does the following:

  • Read the RLN-IP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to be accepted.
  • The title should accurately describe the content.
  • The RLN-IP draft must have been sent to the RLN-IP development mailing list for discussion.
  • Motivation and backward compatibility (when applicable) must be addressed.
  • The defined Layer header must be correctly assigned for the given specification.
  • Licensing terms must be acceptable for RLN-IPs.

If the RLN-IP isn't ready, the editor will send it back to the author for revision, with specific instructions.

Once the RLN-IP is ready for the repository it should be submitted as a "pull request" to the RLN-IPs git repository where it may get further feedback.

The RLN-IP editor will:

  • Assign a RLN-IP number in the pull request.
  • Merge the pull request when it is ready.

The RLN-IP editors are intended to fulfill administrative and editorial responsibilities. The RLN-IP editors monitor RLN-IP changes, and update RLN-IP headers as appropriate.

RLN-IP format and structure

Specification

RLN-IPs should be written in markdown format.

Each RLN-IP should have the following parts:

  • Preamble -- Headers containing metadata about the RLN-IP (see below).
  • Abstract -- A short (\~200 word) description of the technical issue being addressed.
  • Copyright -- The RLN-IP must be explicitly licensed under acceptable copyright terms (see below).
  • Specification -- The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations.
  • Motivation -- The motivation is critical for RLN-IPs that want to change the RLN protocol. It should clearly explain why the existing protocol is inadequate to address the problem that the RLN-IP 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. The rationale should provide evidence of consensus between stakeholders and discuss important objections or concerns raised during discussion.
  • Backwards compatibility -- All RLN-IPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The RLN-IP must explain how the author proposes to deal with these incompatibilities.
  • Reference implementation -- The reference implementation must be completed before any RLN-IP is given status "Final", but it need not be completed before the RLN-IP is accepted. It is better to finish the specification and rationale first and reach consensus on it before writing code. The final implementation must include test code and documentation appropriate for the RLN protocol.

RLN-IP header preamble

Each RLN-IP must begin with an RFC 822 style header preamble. The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.

  RLN-IP: <RLN-IP number, or "?" before being assigned>
  Title: <RLN-IP title; maximum 44 characters>
  Author: <list of authors' real names and email addrs>
* Discussions-To: <email address>
* Comments-Summary: <summary tone>
  Comments-URI: <links to wiki page for comments>
  Status: <Draft | Active | Proposed | Deferred | Rejected |
           Withdrawn | Final | Replaced | Obsolete>
  Type: <Standards Track | Informational | Process>
  Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
  License: <abbreviation for approved license(s)>
* License-Code: <abbreviation for code under different approved license(s)>
* Post-History: <dates of postings to RLN-IP mailing list, or link to thread in mailing list archive>
* Requires: <RLN-IP number(s)>
* Replaces: <RLN-IP number>
* Superseded-By: <RLN-IP number>

The Author header lists the names and email addresses of all the authors/owners of the RLN-IP. The format of the Author header value must be

Random J. User <address@dom.ain>

If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions.

While a RLN-IP is in private discussions (usually during the initial Draft phase), a Discussions-To header will indicate the mailing list or URL where the RLN-IP is being discussed. No Discussions-To header is necessary if the RLN-IP is being discussed privately with the author, or on the RLN-IP email mailing lists.

The Type header specifies the type of RLN-IP: Standards Track, Informational, or Process.

The Created header records the date that the RLN-IP was assigned a number, while Post-History is used to record when new versions of the RLN-IP are posted to RLN-IP mailing lists. Dates should be in yyyy-mm-dd format, e.g. 2001-08-14. Post-History is permitted to be a link to a specific thread in a mailing list archive.

RLN-IPs may have a Requires header, indicating the RLN-IP numbers that this RLN-IP depends on.

RLN-IPs may also have a Superseded-By header indicating that a RLN-IP has been rendered obsolete by a later document; the value is the number of the RLN-IP that replaces the current document. The newer RLN-IP must have a Replaces header containing the number of the RLN-IP that it rendered obsolete.

Auxiliary Files

RLN-IPs may include auxiliary files such as diagrams. Auxiliary files should be included in a subdirectory for that RLN-IP.

RLN-IP types

There are four kinds of RLN-IP:

  • A Governamce RLN-IP describes changes to how technical standards are decided upon, the engagement process with RLN stakeholders, and the release process for RLN technical standards
  • A Standards Track RLN-IP describes any change that affects most or all RLN implementations, such as a change to the network protocol, or any change or addition that affects the interoperability of applications using RLN. Standards Track RLN-IPs consist of two parts, a design document and a reference implementation.
  • An Informational RLN-IP describes an RLN design issue, or provides general guidelines or information to the RLN community, but does not propose a new feature. Informational RLN-IPs do not necessarily represent an RLN community consensus or recommendation, so users and implementors are free to ignore Informational RLN-IPs or follow their advice.
  • A Process RLN-IP describes a process surrounding the RLN, or proposes a change to (or an event in) a process. Process RLN-IPs are like Standards Track RLN-IPs but apply to areas other than the RLN protocol itself. Unlike Informational RLN-IPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in RLN development.

RLN-IP status field

Specification

The typical paths of the status of RLN-IPs are as follows:

Champions of a RLN-IP may decide on their own to change the status between Draft, Deferred, or Withdrawn. A RLN-IP editor may also change the status to Deferred when no progress is being made on the RLN-IP.

A RLN-IP may only change status from Draft (or Rejected) to Proposed, when the author deems it is complete, has a working implementation (where applicable), and has stakeholder support to progress it to the Final status.

A Proposed RLN-IP may progress to Final only when specific criteria reflecting real-world adoption has occurred. This is different for each RLN-IP depending on the nature of its proposed changes, which will be expanded on below. Evaluation of this status change should be objectively verifiable, and/or be discussed on the development mailing list.

When a Final RLN-IP is no longer relevant, its status may be changed to Replaced or Obsolete (which is equivalent to Replaced). This change must also be objectively verifiable and/or discussed.

A process RLN-IP may change status from Draft to Active when it achieves rough consensus on the mailing list. Such a proposal is said to have rough consensus if it has been open to discussion on the development mailing list for at least one month, and no person maintains any unaddressed substantiated objections to it. Addressed or obstructive objections may be ignored/overruled by general agreement that they have been sufficiently addressed, but clear reasoning must be given in such circumstances.

Progression to Final status

An RLN-IP moves to Final status when it is assigned to an RLN Protocol version by the steering committee. At that point it becomes part of that version of the standard. Technology providers seeking to be adopt this standard should publish clearly which version of the standard they are adhering to.

RLN-IP comments

Specification

Each RLN-IP should, in its preamble, link to a public wiki page with a summary tone of the comments on that page. Reviewers of the RLN-IP who consider themselves qualified, should post their own comments on this wiki page. The comments page should generally only be used to post final comments for a completed RLN-IP. If a RLN-IP is not yet completed, reviewers should instead post on the applicable development mailing list thread to allow the RLN-IP author(s) to address any concerns or problems pointed out by the review.

Pages must be named after the full RLN-IP number (eg, "RLN-IP 0001") and placed in the "Comments" namespace. For example, the link for RLN-IP 1 will be https://github.com/RLN-IPs/wiki/Comments:RLN-IP-0001 .

Comments posted to this wiki should use the following format:

--, <Date of posting, as YYYY-MM-DD>

RLN-IPs may also choose to list a second forum for RLN-IP comments, in addition to the RLN-IPs wiki. In this case, the second forum's URI should be listed below the primary wiki's URI.

After some time, the RLN-IP itself may be updated with a summary tone of the comments. Summary tones may be chosen from the following, but this RLN-IP does not intend to cover all possible nuances and other summaries may be used as needed:

  • No comments yet.
  • Unanimously Recommended for implementation
  • Unanimously Discourage for implementation
  • Mostly Recommended for implementation, with some Discouragement
  • Mostly Discouraged for implementation, with some Recommendation

For example, the preamble to RLN-IP 1 might be updated to include the line:

Comments-Summary: No comments yet.
Comments-URI:https://github.com/RLN-IPs/wiki/Comments:RLN-IP-0001
https://some-other-wiki.org/RLN-IP_1_Comments

These fields must follow the "Discussions-To" header defined in RLN-IP 1 (if that header is not present, it should follow the position where it would be present; generally this is immediately above the Status header).

To avoid doubt: comments and status are unrelated metrics to judge a RLN-IP, and neither should be directly influencing the other.

RLN-IP licensing

Specification

New RLN-IPs may be accepted with the following licenses. Each new RLN-IP must identify at least one acceptable license in its preamble. The License header in the preamble must be placed after the Created header. Each license must be referenced by their respective abbreviation given below.

For example, a preamble might include the following License header:

License: BSD-2-Clause
GNU-All-Permissive

In this case, the RLN-IP text is fully licensed under both the OSI-approved BSD 2-clause license as well as the GNU All-Permissive License, and anyone may modify and redistribute the text provided they comply with the terms of *either* license. In other words, the license list is an "OR choice", not an "AND also" requirement.

RLN-IPs are not required to be *exclusively* licensed under approved terms, and may also be licensed under unacceptable licenses *in addition to* at least one acceptable license. In this case, only the acceptable license(s) should be listed in the License and License-Code headers.

Not acceptable licenses

All licenses not explicitly included in the above lists are not acceptable terms for a RLN-IP unless a later RLN-IP extends this one to add them.

See Also