AEP 1: AEP Purpose and Guidelines

	ArmoniK Enhancement Proposal
AEP	1
Title	AEP Purpose and Guidelines
Author	Dylan Brasseur <dbrasseur@aneo.fr>
Status	Active
Type	Process
Creation Date	2023-10-23

What is an AEP ?

AEP stands for ArmoniK Enhancement Proposal. An AEP is a design document providing information to the ArmoniK community, or describing a new feature for ArmoniK, its processes or environment. The AEP should provide a concise technical specification of the feature and a rationale for the feature.

We intend AEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into ArmoniK. The AEP author is responsible for building consensus within the community and documenting dissenting opinions.

Because the AEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed on GitHub.

AEP Audience

The typical primary audience for AEPs is the ArmoniK Developer Team.

However, other parts of the ArmoniK community may also choose to use the process (particularly for Informational AEPs) to document expected API conventions and to manage complex design coordination problems that require collaboration across multiple projects. External contributors should also follow the guidelines established by the AEPs.

AEP Types

There are three kinds of AEP:

1. A Standard AEP describes a new feature or implementation for ArmoniK.

2. An Informational AEP describes an ArmoniK design issue, or provides general guidelines or information to the ArmoniK community, but does not propose a new feature. Informational AEPs do not necessarily represent an ArmoniK community consensus or recommendation, so users and implementers are free to ignore Informational AEPs or follow their advice.

3. A Process AEP describes a process surrounding ArmoniK, or proposes a change to (or an event in) a process. Process AEPs are like Standard PEPs but apply to areas other than ArmoniK itself. They may propose an implementation, but not to ArmoniK’s codebase; they often require community consensus; unlike Informational AEPs, 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 ArmoniK development. Any meta-AEP is also considered a Process AEP.

AEP Workflow

ArmoniK Developer Team

In AEPs, the “ArmoniK Developer Team” refers to the team at Aneo in charge of deciding the core functionnalities and direction of ArmoniK. This term does not extend to ArmoniK external contributors. The ArmoniK Developer Team decides whether a proposal should be considered as an AEP and they usually develop the feature described in them. More information about the ArmoniK Developer Team and ArmoniK Governance can be found in AEP-00004.

Submit an idea for ArmoniK

The AEP process begins with a new idea for ArmoniK. It is highly recommended that a single AEP contain a single key proposal or new idea; the more focused the AEP, the more successful it tends to be. Most enhancements and bug fixes don’t need an AEP and can be submitted directly to the ArmoniK issue tracker. The ArmoniK Developer Team reserves the right to reject AEP proposals if they appear too unfocused or too broad.

To submit an idea for an AEP, open an issue on the ArmoniK.Community issue tracker with the idea clearly presented. The discussion about the potential AEP is held in the issue. After reaching a consensus with the community and the ArmoniK Developer Team, the idea can move to the next stage. This step can be skipped by the ArmoniK Developer Team due to internal discussions.

AEP State Diagram

An AEP can be in one of several states as described in this diagram :

        flowchart LR
    Draft-- PR Reviewed and merged -->Accepted
    Accepted-- Specifications are implemented -->Final
    Accepted-. Implementation had unforseen consequences .->Rejected
    Draft-. PR is not accepted .->Rejected
    Final-. Implemented AEP is superseded .->Replaced
    Draft-- PR reviewed, merged, no implementation -->Active
    Active-. AEP is superseded .->Replaced
    Active-. Details added or corrections .->Active
    

Transitions are described in the workflow below.

Creating the AEP

Once a consensus is reached within the initial issue, the author forks the ArmoniK.Community and creates an aep-XXXXX.md file in the AEP directory, where XXXXX corresponds to the next available AEP number. The AEP number is a zero-padded 5 digits number. The next available AEP number is a number which is not used in the main repository or is not used in an open pull request in the ArmoniK.Community repository. The author then writes the AEP following the guidelines and rules in AEP-00001 (the present document). The discussions in the issue must be taken into account and should be referenced in the AEP. A pull request is then created to merge the fork into the ArmoniK.Community repository.

The discussions regarding the AEP are continued in the pull request itself. Suggested revisions to the AEP should include the potential adjustments to specifications, clarifications of the specifications, correction to spelling of the AEP itself (grammar, sentence structure…), or any relevant point missing or unclear that need to be precised. During this time, the AEP is in a Draft state.

The AEP can be directly created on the ArmoniK.Community repository on a separate branch if the author has write access to it.

Accepting and Finalizing the AEP

Once the AEP has been reviewed and can be accepted, it is merged into the ArmoniK.Community repository with its state changed to Accepted. Depending on the acceptations of other AEPs, the AEP number may need to be adjusted. The initial issue receives a comment with a check list containing information on what needs to be done for the AEP to be considered Final. For an AEP to be accepted, it needs to be clear and complete, must represent a net improvement for ArmoniK and must meet the requirements and objectives asked for by the ArmoniK Developer Team.
Once the check list items are implemented and merged, the AEP receives the Final state and the initial issue is closed as completed. When finalizing the AEP, links to relevant technical and/or user documentation can be added to the footnotes.

A Draft AEP can change to the Active state, meaning that it will never be Final. This can be the case for Informational and Process AEPs. They can be either ammended to take new information into account, or be replaced by a superseding AEP, depending on the ArmoniK Development Team’s and the initial author’s choice.

AEP Rejection and Replacement

When in a Draft or in an Accepted state, an AEP can be rejected (or withdrawn) if, after further consideration, the AEP shouldn’t be accepted because of design flaws, issues discovered during the implementation process or if the proposal was a bad idea after all. This rejection can either be mandated by the ArmoniK Developer Team, or be due to a withdrawal by the author of the AEP (with the consent of the ArmoniK Developer Team). In both cases, the AEP changes to a Rejected state. The initial issue will be closed as “not completed”, but may be reopened if the idea is deemed of importance and relevance again. An initially Accepted AEP that is rejected during implementation will keep its place in the repository. A Rejected Draft AEP will not be merged.

If a subsequent AEP is made to supersede a Final or Active AEP, the superseded AEP changes to the Replaced state and its header must then contain the “Superseded-By” field.

What constitutes an AEP ?

Each AEP should have the following parts/sections:

1. Preamble – Fields in a table format containing meta-data about the AEP, including the AEP number, a short descriptive title, the names, and optionally the contact info for each author, etc. The table is preceded by a top-level heading with the AEP number and short title.

2. Abstract – a short description of the technical issue being addressed.

3. Motivation – The motivation is critical for AEPs that want to change ArmoniK’s functionalities, ecosystem or processes. It should clearly explain why the existing specification is inadequate to address the problem that the AEP solves. This can include collecting documented support for the AEP from important projects using ArmoniK or belonging to the ArmoniK ecosystem. AEP submissions without sufficient motivation may be rejected.

4. Rationale – The rationale fleshes out the specification by describing 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 softwares.
   The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

5. Specification – The technical specification should describe the syntax, semantics and functionning of any new ArmoniK feature. The specification should be detailed enough to allow proper implementations for at least the current major languages used supported by ArmoniK.Api (C#, C++, Python, TypeScript…).

6. Backwards Compatibility – All AEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The AEP must explain how the author proposes to deal with these incompatibilities. AEP submissions without a sufficient backwards compatibility treatise may be rejected outright.

7. Security Implications – If there are security concerns in relation to the AEP, those concerns should be explicitly written out to make sure reviewers of the AEP are aware of them.

8. How to Teach This – For an AEP that adds new functionality or changes ArmoniK’s behavior, it is helpful to include a section on how to teach users, new and experienced, how to apply the AEP to their work. This section may include key points and recommended documentation changes that would help users adopt a new feature or migrate their code to use an ArmoniK version change.

9. Reference Implementation – The reference implementation must be completed before any AEP is given status “Final”, but it need not be completed before the AEP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of “rough consensus and running code” is still useful when it comes to resolving many discussions of API details. The final implementation must include test code and documentation appropriate for both the ArmoniK Developers and Users.

10. Rejected Ideas – Throughout the discussion of an AEP, various ideas will be proposed which are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This both helps record the thought process behind the final version of the AEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions. In a way this section can be thought of as a breakout section of the Rationale section that is focused specifically on why certain ideas were not ultimately pursued.

11. Open Issues – While an AEP is in draft, ideas can come up which warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the AEP to be ready for consideration are complete and reduces people duplicating prior discussion.

12. Footnotes – A collection of footnotes cited in the AEP, and a place to list non-inline hyperlink targets.

13. Copyright/license – Each new AEP must be placed under a dual license of public domain and CC0-1.0-Universal (see this AEP for an example).

AEP Formats and Templates

AEPs are UTF-8 encoded, english text files using the GitHub-flavored markdown format. Using undocumented Markdown syntax which “works” at one point with GitHub is discouraged, as it could break later without notice. Further specifications can be found in the GitHub documentation. The AEP must pass the linter executed via the following command at the root of the repository:

npm run lint:md

An AEP format guide and template is available in AEP-00005.

AEP Header Preamble

Each AEP must begin with a heading and table using the following format:

## AEP {AEP number}: {AEP Title}

|                     |ArmoniK Enhancement Proposal|
|---:                 |:--- |
| **AEP**             | AEP number |
| **Title**           | AEP Title |
| **Author**          | Author name <<Author-email>> |
| **Status**          | AEP Status |
| **Type**            | (Standard or Informational or Process) |
| **Requires**        | AEP numbers |
| **ArmoniK Version** | ArmoniK version |
| **Replaces**        | AEP number |
| **Superseded-By**   | AEP number |
| **Creation Date**   | Creation date of the AEP (YYYY-MM-DD format) |

The “Requires”, “ArmoniK Version”, “Replaces” and “Superseded-By” fields can be omitted for AEP where they’re not relevant. The Author field lists the names, and optionally the email addresses of all the authors/owners of the AEP. The format of the Author field values must be:

Random J. User <<random@example.com>>

if the email address is included, and just:

Random J. User

if the address is not given. Please mind the double brakets here, as a single braket is transformed into a link, as per GitHub Flavoured Markdown specifications.

The Type field specifies the type of AEP: Standard, Informational, or Process.

Standard AEPs will typically have an ArmoniK Version field which indicates the version of ArmoniK that the feature will be released with. Informational and Process AEPs do not need an ArmoniK Version field.

AEPs may have a Requires header, indicating the AEP numbers that this AEP depends on.

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

The header preamble should use non padded AEP numbers.

Auxiliary Files

AEPs may include auxiliary files such as diagrams (although inline diagrams using Mermaid are preferred). All support files may be placed in a subdirectory called aep-XXXXX, where “XXXXX” is the AEP number.

Changing Existing AEPs

Draft AEPs are freely open for discussion and proposed modification, at the discretion of the authors, until submitted to the ArmoniK Developper Team for review and resolution. Substantive content changes should generally be first proposed on the AEP’s Draft Pull Request, while copyedits and corrections can be submitted as subsequent GitHub pull request. AEP authors with write access to the AEP repository can update the AEPs themselves by using git push or a GitHub PR to submit their changes.

See the Contributing Guide for additional details, and when in doubt, please check first with the AEP author and/or a member of the ArmoniK Developer Team.

Footnotes

This AEP is heavily inspired from PEP 1 used by Python for its specifications.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.