Æternity best current practices (AEXpansions)

Hello,

I assume most of you are aware of the EIP/BIP processes used to standardise various interfaces or propose protocol changes in the Ethereum and Bitcoin communities. We have planned to implement similar processes for a while but now with feedback from the aepp summit, we want to finally get this process started.

The following proposal is limited to non-core issues and intended to be used by anyone who wants to propose interfaces or processes to be adopted by the developer community.

I’d like to use this thread to introduce the process and put it up for discussion.

A couple of things beforehand:

  • the list of editors will be longer
  • we have bigger plans to make this process more dynamic and if possible tie it together with funding of OSS as well but more on that soon
  • there will be a similar process for core issues in the near future
  • I’d be very much interested in opinions as to whether we want to require usable implementations before accepting proposals into the Final state or if this is too much of a burden

Ideally we can wrap up this initial discussion within the next seven days and from that point on use the proposed process.

Introduction/Readme

# Aeternity Expansions

The Aeternity Expansions (AEX), or aexpansions, are standards proposed by the
community at large, i.e. everyone. Some of them can be mandatory in a specific
context, e.g. AEX-1 describes the set of rules governing this repository, but
are restricted to the application layer.


## Goals

The purpose of this repository is to provide a high quality and accessible set
of specifications; ideally together with implementations ready to be used if
applicable.


## Contributing

If you want to contribute please follow these steps:

1. Read AEX-1
2. Fork this repository
3. Add your proposal to your fork, using the template provided
4. Submit a pull request to the AEX repository

Each proposal should go into the `AEX` directory. If you need to embed images
or other assets add a subdirectory in the `assets` directory with the number
of your proposal once assigned, e.g. `assets/aex-1/image.png`.

Everything beyond step 4 is governed by AEX-1.


## Copyright

This README is released under the [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/) license.

And here is AEX-1

# AEX 1

```
AEX: 1
Title: AEX process
Author: Sascha Hanse <[email protected]>
License: CC0-1.0
Discussions-To: <URL>
Status: Draft
Type: Meta
Created: 2019-02-01
```


## Simple Summary

This document describes the process a proposal has to go through in order to
be accepted into the AEX repository.

## Motivation

The purpose of AEXs is to provide high quality and accessible specifications
to be used when developing applications on top of Aeternity.
We intend AEXs to be the primary mechanisms for proposing new standards, for collecting community technical input on an issue, and for documenting the design decisions. Because the AEXs are maintained as text files in a versioned
repository, their revision history is the historical record of the feature
proposal.

## Specification

### AEX Types

There are three types of AEXs:

- A **Standards Track** AEX describes any change or addition that affects the
  interoperability of applications using Aeternity. Standards Track AEXs consist 
  of two parts: a design document and a reference implementation.
- An **Informational** AEX describes a design issue, or provides general
  guidelines or information to the Aeternity community, but does not propose a
  new feature. Informational AEXs do not necessarily represent an Aeternity
  community consensus or recommendation, so users and implementors are free to ignore Informational AEXs or follow their advice.
- A **Meta** AEX describes a process surrounding AEXs or proposes a change to
  (or an event in) a process. They often require community consensus; unlike
  Informational AEXs, 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 Aeternity development.

### Workflow

Parties involved in the process are you, the champion or AEX author and the
AEX editors.

⚠️ Before you begin, vet your idea, this will save you time. Ask the Aeternity
community first if an idea is original to avoid wasting time on something that
will be be rejected based on prior research (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
Aeternity is used. Examples of appropriate public forums to gauge interest around your AEX include the [Aeternity forums](https://forum.aeternity.com)
and the issues section of this repository. In particular, the issues section
of this repository is an excellent place to discuss your proposal with the
community and start creating more formalised language around your AEX.

Your role as the champion is to write the AEX using the style and format
described below, shepherd the discussions in the appropriate forums, and build community consensus around the idea.

#### Stages

| Stage | Purpose | Entrance Criteria | Changes Expected |
|:--|:--|:--|:--|:--|:--|:--|
| Draft | rapid iteration in small/focused working group | none | major |
| Review | review and feedback from editor and other interested parties | initial specification, editor assigned, template filled, authors and editor consider document to be in a state where the general public can give constructive feedback | no major TODOs left |
| Last call (yyyy-mm-dd to yyyy-mm-dd) | indicate that authors and editors consider document to be complete; solicit last round of feedback | at least one working implementation (if applicable), authors and editors deem the proposal complete | minor |
| Final | proposal is considered to be completed | no unaddressed substantiated objections are left | crucial or cosmetic updates only |
| Active | proposal can be in constant flux | no unaddressed substantiated objections are left | crucial or cosmetic updates only |
| Updated | signalling that an updating standard might have to be considered | an updating proposal entered the `Final` state | crucial or cosmetic updates only |
| Superseded | standard should no longer be used | community consensus and verifiable | none |
| Rejected | editors deemed this proposal to be unworkable | proposal was rejected before, authors were unwilling to respond to feedback, too unfocused, too broad, duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility | none |
| Withdrawn | signalling that the proposal is no longer relevant | withdrawn by original authors | none |


```
+---------------+             +---------------+             +---------------+
|     Draft     |------------>|     Review    |<----------->|   Last call   |
+---------------+             +---------------+             +---------------+
   ^      |                 |     ^                       |   |   |   |
   |      v                 |     |                       |   |   |   |
   |  +---------------+     |     |                       |   |   |   |
   |  |   Withdrawn   |<----+-----|-----------------------+   |   |   |
   |  +---------------+           |                           |   |   |
   v                              |                           |   |   |
+---------------+                     |                           |   |   |
|    Rejected   |<--------------------+---------------------------+   |   |
+---------------+                                    -----------------+   |
                                                 |                    |
                                                 v                    v
      +---------------+             +---------------+    +---------------+
      |    Updated    |<----------->|     Final     |    |     Active    |
      +---------------+             +---------------+    +---------------+
              |                             |
              +----------+       +----------+
                         |       |
                         v       v
                     +---------------+
                     |   Superseded  |
                     +---------------+
```

Each status change is requested by the AEX author and reviewed by the AEX
editors. Use a pull request to update the status.

AEXs should be changed from `Draft` or `Review` status, to `Rejected` status,
upon request by any person, if they have not made progress in three years. Such a AEX may be changed to `Draft` status if the champion provides
revisions that meaningfully address public criticism of the proposal, or to `Review` status if it meets the criteria required as described in the previous paragraph.

The transition from `Last Call` to either `Final` or `Active` happens
automatically if during the last call period, typically 14 days, no
substantiated objections are voiced or left unaddressed.

A `Last Call` which results in material changes or substantial unaddressed
technical complaints will cause the AEX to revert to `Review`.


### Transferring AEX Ownership

It occasionally becomes necessary to transfer ownership of AEXs to a new
champion. In general, we'd like to retain the original author as a co-author
of the transferred AEX, 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 AEX process, or
has fallen off the face of the 'net (i.e. is unreachable or isn't responding
to email). A bad reason to transfer ownership is because you don't agree with
the direction of the AEX. We try to build consensus around an AEX, but if
that's not possible, you can always submit a competing AEX.

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


### Editors

For each new AEX that comes in, an editor does the following:

- Read the AEX to check if it is ready: sound and complete. The ideas must
  make technical sense, even if they don't seem likely to get to final status.
- The title should accurately describe the content.
- Check the AEX for language (spelling, grammar, sentence structure, etc.),
  markup (Github flavoured Markdown), code style

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

Once the AEX is ready for the repository, the editor will:

- Assign an AEX number (generally the PR number or, if preferred by the
  author, the Issue # if there was discussion in the Issues section of this
  repository about this AEX)
- Merge the corresponding pull request
- Send a message back to the AEX author with the next step.

In general, the editors: 

- Don't pass judgment on AEXs.
- Are intended to fulfil administrative and editorial responsibilities.
- Monitor AEX changes, and update AEX headers as appropriate.


#### List of editors

- Sascha Hanse (@knarz)

### Format

Successful AEXs should contain most of the following sections:

- **Preamble**: RFC 822 style headers containing metadata about the AEX
- **Simple Summary**: a simplified and layman-accessible explanation of the
  AEX
- **Abstract**: a short (~200 word) description of the (technical) issue being
  addressed
- **Motivation**: clearly explaining why the existing standards are inadequate
  to address the problem that the AEX solves
- **Specification**: should describe the syntax and semantics of any new
  feature and should be detailed enough to allow competing, interoperable
  implementations
- **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 may also provide
  evidence of consensus within the community, and should discuss important
  objections or concerns raised during discussion.
- **Backwards Compatibility**: if a proposal is supposed to supersede another
  proposal without providing backwards compatibility then it should contain a section describing these incompatibilities and their severity. Further, it
  should explain how the author proposes to deal with these incompatibilities. 
- **Test Cases**: links to test cases if applicable
- **Implementations**: implementation or link to implementations, if
  applicable

A AEX template can be found under `AEX-X`.

#### Preamble

Each AEX 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.

```
AEX: <to be assigned by editors>
Title: <AEX title>
Author: <a list of the author's or authors' name(s) and/or username(s), or name(s) and email(s), e.g. (use with the parentheses or triangular brackets): FirstName LastName (@GitHubUsername), FirstName LastName <[email protected]>, FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername)>
License: <license names, abbreviated>
License-Code (*optional): <license names, abbreviated>
Discussions-To: <URL>
Status: <Draft | Active Review | Last Call (yyyy-mm-dd to yyyy-mm-dd) | Final | Updated | Superseded | Rejected | Withdrawn>
Type: <Standards Track | Informational | Meta>
Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
Requires (*optional): <AEX number(s)>
Replaces (*optional): <AEX number(s)>
Superseded-By (*optional): <AEX number(s)>
Updates (*optional): <AEX number(s)>
Updated-By (*optional): <AEX number(s)>
```

Header fields permitting lists must separate elements with commas.

The `Discussions-To` field should point to a discussion of the proposed
standard. Most of the initial work should happen in small, focused working
groups and only posted once it is in a reasonably stable state.
Please try to refrain from having WIP documents or very early drafts in this
repository as they tend orphan.

Each proposal must start in the `Draft` state and will move through the
phases in accordance to the criteria defined in this document.

If a proposal depends on another AEX, the `Requires` field should indicate
so.

`Superseded-By`, `Replaces`, `Updates` and `Updated-By` fields are required
since standards are in constant flux. Editors and authors should make sure
that old AEXs are update where appropriate.


#### Copyright

The following recommended licenses should be used both for code and the
specification:

- [BSD-2-Clause](https://opensource.org/licenses/BSD-2-Clause)
- [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause)
- [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/)
- [GNU-All-Permissive](http://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html)

Each submitted proposal needs to list at least one license. If code is
included, a separate license for it can be specified. The licenses should
be included in the header via the `License` and `License-Code` fields. If
those fields do not cover the requirements, include a copyright section in
your proposal.

```
License: CC0-1.0
License-Code: Apache-2.0
```

Or with multiple licenses:

```
License: CC0-1.0
     BSD-3-Clause
License-Code: Apache-2.0
```

Acceptable licenses:

- ISC: [Internet Systems Consortium License](https://www.isc.org/downloads/software-support-policy/isc-license/)
- Apache-2.0: [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- MIT: [Expat/MIT/X11 license](https://opensource.org/licenses/MIT)
- AGPL-3.0+: [GNU Affero General Public License (AGPL), version 3 or newer](http://www.gnu.org/licenses/agpl-3.0.en.html)
- FDL-1.3: [GNU Free Documentation License, version 1.3](http://www.gnu.org/licenses/fdl-1.3.en.html)
- GPL-2.0+: [GNU General Public License (GPL), version 2 or newer](http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
- LGPL-2.1+: [GNU Lesser General Public License (LGPL), version 2.1 or newer](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html)

## References

Many parts of this document are inspired by or adapted with only minor modifications from many of the already existing standardisation processes.

- [EIP-1](https://eips.ethereum.org/EIPS/eip-1)
- [BIP-2](https://github.com/bitcoin/bips/blob/master/bip-0002.mediawiki) 
- [TC39](https://tc39.github.io/process-document/)
- [The Internet Standards Process](https://www.rfc-editor.org/rfc/rfc2026.txt)
7 Likes

I would totally agree to this, but I think from case to case this requirement may be dropped and for some types of proposals it should not be required at all. But I see this well described in the ABCP-1 Types. Pseudocode implementations should be fine as well, I’d assume.

In my opinion ABCP-1 looks great.

1 Like

Is there a dedicated github repo where the proposals should go to?

Yes, there will be a proposals repo. The above defines the process on how things get accepted there. Feedback is welcome!

I’m asking myself how to deal with

Specification: should describe the syntax and semantics of any new feature and should be detailed enough to allow competing, interoperable implementations

If you are not a technical person. Writing syntax and semantics of any new features might be a show stopper for some people. Is it possible that less technical users write specifications in form of user stories for example or does it need to go down to protocol level and deep understanding on how it would be implemented in a later stage?

EDIT: i’ve copied the text from above, the INTRO and the ABCP-1 into a markdown editor here for better readability. I hope this is ok, i’ll delete if requested: https://hackmd.aepps.com/KwFgDAjMYEYCYFoDsA2CAOBI4gEwJhHQDMEBmHJY4lGCOGAYyA==?view

1 Like

There is nothing stopping them from submitting a draft to the repository but with the proposed ruleset it would not be able to progress past the Draft phase.
Ideally a person with a good idea but not the required expertise to specify it properly should seek out collaborators with the required skills.

We want to encourage people to solicit feedback on their ideas before they submit a draft to the repository. That might be a good point at which they could convince others that their proposal is worth engaging with.

3 Likes

Is there any example of a feature or standard of any kind that is following the ABCP Standard already so i can get inspired / guided a bit?

I’m planning to write up specifications on a potential Open KYC Standard (connecting pubkeys with different stages of KCY from posting a signed message on your gist and social media profiles up to partnerships with KYC provider).

I’ve difficulties to start and could need some guidance. Should i just copy and paste the ABCP and create a new forum post or is it better do do that directly on github in a github issue or is this the complete wrong approach to it and i should first do it in private and post it when its more then just a raw draft with a few cornerstones and bulletpoints?

Best
Emin

For our ABCPs we have no examples, yet. Looking at accepted ERCs/EIPs could help.

All of those are valid approaches. Based on how far you are with your ideas, I would recommend ordering the starting points as follows (from least to most progress):

Private|Forum → github Issue → github pull request

1 Like

“Standards Track” ABCPs and “Informational” ABCPs are defined also in terms of “change or addition” and “issue”, that imply existence of preceding/seed normative content. It would be beneficial to issue an informational ABCP with outline and pointers to existing normative material in scope of ABCPs that ABCP authors are expected to be aware of.

For the rest, the proposal looks great.

1 Like

I don’t necessarily think that »change or addition« implies prior existence, addition could be going from none to some but I’ll make the wording more explicit.

The second point is a good one, thank you

1 Like

I’d like to mention here, even if its a bit late, that the majority of people voted for the name:

aexpansions during the aepps summit in Antalya. A naming could be

aex-1 or aexpansion-1

I prefer the shorter version AEX-1, AEX-2. Would you mind to adapt that (as there has been some kind of “small governance decision” on this already?).

Best regards
Emin

PS: i really like ABCP but it was not up for a vote back then. I’m not sure if we documented or communicated results from the aepps summit yet, which we should do.

1 Like

I second that, as a disclaimer I was also part of the vote at the aepps summit and voted for aexpansions. For me Aeternity best current practices sounds a bit confusing. Also for the abbreviation I would also go with AEX-1.

I updated the first post with the changed name.

1 Like

I updated the title wit (AEXpansions) i hope this is fine.

I will create the repository at the end of the weekend unless there are any more concerns voiced.

Just for the record, I don’t particularly like the name aexpansions, since an expansion—to me anyway—would imply changes to the protocol, e.g. taking the existing protocol and expanding it.

Could you elaborate? What is confusing about the concept of »best practices«?

I’m familiar with the term »best practices« and »best current practices« but the current in »best current practices« has a weird ring to it, this is just a personal opinion.

GitHub - aeternity/AEXs: Aeternity expansions repository — application layer standards is now live. This thread can still be used for discussions about the initial version of AEX-1. Anything beyond that should either happen in a separate thread or in the repository itself.

1 Like

First AEX are coming in: AEXs/aex-2.md at 238daaa61a94e494bab338066aef7cf16103c3aa · aeternity/AEXs · GitHub

2 Likes

“current best practices” reads right to me.