How to define and propose new ideas, features, processes and policies to the TokeSocial district.
TDP: 0000
Title: TokeSocial District Proposal Format
Author: Dan Kelly ([email protected])
Status: Active
Type: Process
Created: 2018-02-26
Table of Contents
- TDP: TokeSocial District Proposal Format
- What is a TDP?
- TDP Types
- TDP Workflow
- TokeSocial Leadership
- Submitting a Proposal
- What belongs in a successful TDP?
- Consensus
- TDP Formats and Templates
- TDP Header Preamble
- Auxiliary Files
- Transferring TDP Ownership
- TDP Editors
- TDP Editor Responsibilities & Workflow
- History
- Changelog
TDP: TokeSocial District Proposal Format
This document describes the mechanism for proposing policy for discussing TokeSocial's ecosystem of activities and features.
What is a TDP?
TDP stands for TokeSocial District Proposal Format. A TDP is a design document providing information to the TokeSocial community, or describing a new activity or feature for TokeSocial district or ecosystem, or its processes, environment, or policy. The TDP should provide a concise technical specification of a proposal and a rationale for it.
We intend TDP to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions. The TDP author is responsible for building consensus within the community and documenting dissenting opinions.
Because the TDP are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
TDP Types
There are three kinds of TDP:
- An Informational TDP describes a TokeSocial design feature, challenge, issue or event; but it does not propose a new change. These can be useful to describe and log an historical event or decision taken at some point, or call for solutions for a given problem to the community. Information TDPs are often the precursor to a successful process, standard or business track TDP.
- A Process TDP describes a process surrounding TokeSocial, or proposes a change to (or an event in) a process. They may propose an implementation, procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in TokeSocial development. Any meta-TDP is also considered a Process TDP.
- A Standard Track TDP describes any new feature to TokeSocial. This is useful for proposals who's effort is to make TokeSocial more enjoyable and attractive to newcomers as well as retain loyal visitors. This could include new activities, environment or design changes to the vr modeling, websites, marketing, etc. he standard track specifically excludes any feature which the primary focus is revenue based. These prosals should be filled under the business track.
- A Business Track TDP describes any new feature or change who's goal is to bring revenue into TokeSocial. This is useful for proposals who's effort is to make some revenue for the TokeSocial investors in a fun manner.
TDP Workflow
TokeSocial Leadership
The TokeSocial district leaders are currently the team charged with the task of building the infrastructure and procedures to build the initial TokeSocial experience. Most initial TDP are authored by them, and they are the main promoters of the process and the district.
Submitting a Proposal
The TDP process begins with a new idea for TokeSocial. Each potential TDP must have a champion -- someone who writes the TDP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The TDP champion (a.k.a. Author) should first attempt to ascertain whether the idea is TDP-able. Posting an issue to the GitHub TDP repository is the best way to go about this.
Once the champion has asked the TokeSocial community as to whether an idea has any chance of acceptance, a draft TDP should be presented as a pull request to that repository. This gives the author a chance to flesh out the draft TDP to make it properly formatted, of high quality, and to address additional concerns about the proposal. Following a discussion, mention one of the TDP editors to review the TDP draft and accept the pull request. This draft must be written in TDP style as described below, else it will be rejected without further regard until proper formatting rules are followed.
TDP authors are responsible for collecting community feedback on both the initial idea and the TDP before submitting it for review. However, wherever possible, long open-ended discussions on chat or public forums should be avoided. Strategies to keep the discussions efficient include: setting up a channel within the chat server for the topic, having the TDP author accept private comments in the early design phases, setting up a wiki page, etc. TDP authors should use their discretion here.
It is highly recommended that a single TDP contain a single key proposal or new idea. The more focused the TDP, the more successful it tends to be. If in doubt, split your TDP into several well-focused ones.
The TDP editors assign TDP numbers and change their status. Please send all TDP-related email to the TDP editor, which is listed under TDP Editors below. Also see TDP Editor Responsibilities & Workflow. The TDP editor reserves the right to reject TDP proposals if they appear too unfocused or too broad.
Authors MUST NOT self assign TDP numbers, but should use an alias such as "dsd-newavatars" which includes the TDP subject.
If the TDP editor approves, he will assign the TDP a number, label it as the appropriate TDP Type, give it status "Draft", and merge it to the main branch of the TDP git repository. The TDP editor will not unreasonably deny a TDP. Reasons for denying TDP status 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 contrarial to the TokeSocial philosophy. For a TDP 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 TDP author may update the Draft as necessary in the git repository. Updates to drafts may also be submitted by the author as pull requests.
Standards Track TDP (and Business Track TDP when appropriate) consist of two parts, a design document and a reference implementation. The TDP should be reviewed and accepted before a reference implementation is begun, unless a reference implementation will aid people in studying the TDP. Standards Track TDP must include an implementation -- in the form of code, a patch, or a URL to same -- before it can be considered Final.
Once a TDP has been accepted, the reference implementation must be completed. When the reference implementation is complete and accepted by the community, the status will be changed to "Final".
A TDP can also be assigned status "Deferred". The TDP author or editor can assign the TDP this status when no progress is being made on the TDP. Once a TDP is deferred, the TDP editor can re-assign it to draft status.
A TDP 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.
TDP can also be superseded by a different TDP, rendering the original obsolete. This is intended for Informational TDP, where version 2 of an API can replace version 1.
Some Informational and Process TDP may also have a status of "Active" if they are never meant to be completed. E.g. TDP 0000 (this TDP).
What belongs in a successful TDP?
Each TDP should have the following parts:
- Preamble -- RFC 822 style headers containing meta-data about the TDP, including the TDP number, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc.
- Abstract -- a short (~200 word) description of the technical issue being addressed.
- Copyright/public domain -- Each TDP must either be explicitly labelled as placed in the public domain (see this TDP as an example) or licensed under the Open Publication License.
- 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 for any of the current TokeSocial features.
- Motivation -- The motivation is critical for TDP that wants to implement within TokeSocial. It should clearly explain why the existing specification is inadequate to address the problem that the TDP solves. TDP submissions without sufficient motivation may be rejected outright.
- 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 elsewhere.
- The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
- Backwards Compatibility -- All TDP that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The TDP must explain how the author proposes to deal with these incompatibilities. TDP submissions without a sufficient backwards compatibility treatise may be rejected outright.
- Reference Implementation -- The reference implementation must be completed before any TDP is given status "Final", but it need not be completed before the TDP 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 Decentraland protocol and TokeSocial policies.
Consensus
The term "consensus" is used loosely in this document, in most cases refers to general consensus and simply "getting a feel for the crowd". When the term "consensus" is used in respect with final voting of proposals, it is defined as 67% of responding registered contributors within 7 days of starting the vote or 67% of all registered contributing members at anytime.
TDP Formats and Templates
TDP must be written markdown format. There is an example TDP which can be copied from tdp/example.md.
TDP Header Preamble
Each TDP 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.
TDP: <TDP number>
Title: <TDP title>
Author: <list of authors names and optionally, email addresses>
# Discussions-To: <email address>
Status: <Draft | Active | Accepted | Deferred | Rejected |
Withdrawn | Final | Superseded>
Type: <Standards Track | Informational | Process>
Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
# Replaces: <TDP number>
# Superseded-By: <TDP number>
The Author header lists the names, and email addresses of all the authors/owners of the TDP. The format of the Author header value must be
Author: Random A. User <[email protected]>
If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions.
Author: Random A. User <[email protected]>
Author: Random B. User <[email protected]>
Note: The Resolution header is required for Standards Track TDP only. It contains a URL that should point to an email message or other web resource where the pronouncement about the TDP is made.
While a TDP is in private discussions (usually during the initial Draft phase), a Discussions-To header will indicate a chatroom, forum thread, or URL where the TDP is being discussed. No Discussions-To header is necessary if the TDP is being discussed privately with the author, or on Decentraland's RocketChat chat service.
The Type header specifies the type of TDP: Informational, Standards, Process, or Business track.
The Created header records the date that the TDP was assigned a number, while Post-History is used to record the dates of when new versions of the TDP are posted to the TokeSocial District Proposal GitHub issue tracker. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14.
TDP may have a Requires header, indicating the TDP numbers that this TDP depends on.
TDP may also have a Superseded-By header indicating that a TDP has been rendered obsolete by a later document; the value is the number of the TDP that replaces the current document. The newer TDP must have a Replaces header containing the number of the replaced TDP.
Auxiliary Files
TDP may include auxiliary files such as diagrams. Image files should be included in a subdirectory for that TDP. Auxiliary files must be named TDP-XXXX-Y.ext, where "XXXX" is the TDP number, "Y" is a serial number (starting at 1), and "ext" is replaced by the actual file extension (e.g. "png").
Transferring TDP Ownership
It occasionally becomes necessary to transfer ownership of TDP to a new champion. In general, we'd like to retain the original author as a co-author of the transferred TDP, 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 TDP process, or has fallen off the face of the 'net' (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the TDP. We try to build consensus around a TDP, but if that's not possible, you can always submit a competing TDP.
If you are interested in assuming ownership of a TDP, send a message asking to take over, addressed to both the original author and the TDP editor. If the original author doesn't respond to email in a timely manner, the TDP editor will make a unilateral decision (it's not like such decisions can't be reversed :).
TDP Editors
The current TDP editor is Daniel Kelly who can be contacted at
[email protected]
TDP Editor Responsibilities & Workflow
The TDP editor watches the TDP repository on GitHub. All TDP-related correspondence should be sent (or CC'd) to the [email protected].
For each new TDP that comes in an editor does the following:
- Read the TDP 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.
- Edit the TDP for language (spelling, grammar, sentence structure, etc.), markup (visual formatting), and code style.
If the TDP isn't ready, the editor will send it back to the author for revision, with specific instructions.
Once the TDP is ready for the repository it should be submitted as a "pull request" to the TokeSocial Proposals repository on GitHub where it may get further feedback.
The TDP editor will:
- Assign a TDP number (the next available number, or maybe some number grouped together with similar TDP, but sometimes a special/joke number, like 1337) in the pull request comments.
- Merge the pull request when the author is ready (allowing some time for further peer review).
- List the TDP in README
- Send email back to the TDP author with next steps.
The TDP editors are intended to fulfill administrative and editorial responsibilities. The TDP editors monitor TDP changes, and correct any structure, grammar, spelling, or markup mistakes we see.
History
This document is heavily based on Decentraland's DSP format.
Changelog
- Febuary 26th, 2018: Initial document
- Febuary 27th, 2018: Updated grammar, added clarification to the term "consensus"