FEP-a4ed: The Fediverse Enhancement Proposal Process

Standards Fediverse Enhancement Proposals
, ,
1

source: https://codeberg.org/fediverse/fep/src/branch/main/feps/fep-a4ed.md

---
authors: @pukkamustard
status: FINAL
dateReceived: 2020-10-16
dateFinalized: 2021-01-18
---

FEP-a4ed: The Fediverse Enhancement Proposal Process

Summary

A Fediverse Enhancement Proposal (FEP) is a document that provides information to the Fediverse community. The goal of a FEP is to improve interoperability and well-being of diverse services, applications and communities that form the Fediverse.

This document describes the scope, format and process of publishing Fediverse Enhancement Proposals.

Scope and Objectives

A Fediverse Enhancement Proposal (FEP) should be a concise and focused documentation of a specific topic that is of interest to the Fediverse community.

A proposal should always have the intention of improving the interoperability and well-being of diverse services, applications and community of the Fediverse.

The Fediverse includes applications, services and communities using the ActivityPub protocol and other protocols that foster decentralized and diverse social media and culture.

Proposals may include descriptions of technical protocols and mechanism, documentation of experimental work or current best practices.

Proposals are not limited to technical topics and may focus on social and cultural aspects.

Proposals may be entertaining and humorous (unlike this proposal).

Language, Document Structure and Format

All Fediverse Enhancement Proposals must be written in English, be properly formatted as CommonMark [CommonMark] and be reasonably grammatical.

Authors should use inclusive language and examples and refrain from using oppressive terminology [Internet-Draft-terminology].

Proposal Title and Identifier

Every Fediverse Enhancement Proposals must have a descriptive title.

An identifier is computed from the proposal title as the first 4 digits of the sha256 hash (in hex). The identifier can be computed from the title with standard Unix tools:

$ echo -n "The Fediverse Enhancement Proposal Process" | sha256sum | cut -c-4
a4ed

By using the hash of the title as identifier we reduce the burden on editors to assign unique ids. This requires proposal titles to be unique.

Metadata

Proposal metadata is placed at the top of the document as key-value pairs between opening and closing ~—~.

Following metadata key-value pairs may be placed at the top of a proposal:

  • authors: A comma separated list of authors of the proposal.
  • status: Indicates the proposal status. Can be either DRAFT, WITHDRAWN or FINAL.
  • dateReceived: Date of when the proposal was added to the repository (when status is set to DRAFT).
  • dateWithdrawn: Date of when the proposal status was set to WITHDRAWN (only for proposals with status WITHDRAWN).
  • dateFinalized: Date of when the proposal status was set to FINAL (only for proposals with status FINAL).
  • relatedFeps: A comma separated list of related FEPs (e.g. FEP-a4ed, FEP-141a, FEP-686f).
  • replaces: A comma separated list of FEPs that are replaced by the proposal.
  • replacedBy: Identifier of a FEP that replaces the proposal.

Future FEPs may specify additional metadata fields.

Required Sections

Every FEP should include at least the following sections:

  • Summary: A short (no more than 200 words) summary of the proposal.
  • Copyright: Indicating that the proposal has been placed in the public domain.

Following sections may be included in a proposal:

  • History: An overview of previous related efforts and how they relate to the proposal.
  • Implementations: If applicable an overview of services or applications that implement the proposal at time of submission.
  • References: A list of documents and resources referenced by the proposal.

Copyright

Fediverse Enhancement Proposals must be placed in the public domain by the authors with a CC0 1.0 Universal (CC0 1.0) Public Domain Dedication.

The Fediverse Enhancement Proposals Process

                                     +-------+
                           +-------> | FINAL | 
                           |         +-------+
         +-------+         |
-------->| DRAFT | --------+
         +-------+         |
             ^             |         +-----------+
             |             +-------> | WITHDRAWN |
             |                       +-----------+
             |                             |
             +-----------------------------+
  1. A Fediverse Enhancement Proposal can be submitted by individuals or groups of individuals (authors). See the SUBMISSION.md file for a list of accepted submission methods.
  2. Within seven days one of the editors will read and respond to the proposal. The editor checks if the proposal conforms to the required structure and fits the scope and objective of the FEPs. The editor may request the authors to clarify, justify, or withdraw the proposal. Such a request must not reflect the personal bias of an editor. Rather, it will be made strictly to maintain a high quality of submissions. The editors reserve the right to reject a submission when a proposal amounts to blatant misuse of the process. The authors may seek feedback from the wider community if the submitted proposal is rejected or clarifications are requested.
  3. If a FEP editor approves a submission it receives the status DRAFT and is added to the repository.
  4. While a proposal has the status DRAFT:
    • Authors are responsible for initiating community discussion and collecting feedback.
    • Authors may submit updates to the proposal which will be checked in to the repository by an editor.
    • Authors may withdraw the submission upon which an editor will set the status of the submission to WITHDRAWN.
  5. After at least 60 days the authors may request the proposal to be finalized. This is done by requesting final comments on the proposal.
    • If there are no community objections within 14 days and the authors can show that they have initiated sufficient awareness and discussion of the proposal, an editor will set the status of the submission to FINAL.
  6. If after 120 days the authors have not requested the proposal to be finalized or there is no community consensus, an editor will set the status of the submission to WITHDRAWN.
  7. A proposal with status FINAL can not be changed or updated in a way that would lead to adjustments to implementations. Minor corrections are allowed.
  8. Any substantial change to finalized proposal must be submitted as a separate FEP.
  • The new FEP MUST include a replaces metadata attribute pointing to FEPs it supersedes.
  • If the new FEP becomes FINAL, the original one MUST point to it in an added replacedBy metadata attribute.
  1. A proposal with status WITHDRAWN remains in the repository and can be resubmitted.

Editors

A list of editors is maintained in the EDITORS.md file at the root of the FEP repository.

Submission Methods

A list of methods in which a proposal may be submitted is maintained in the SUBMISSION.md file at the root of the FEP repository.

FEP-a4ed

FEP-a4ed (The Fediverse Enhancement Proposal Process) is a living document and can be updated despite having the FINAL status.

History

The process and format described in this proposal is influenced by other community driven documentation efforts such as the BitTorrent Enhancement Proposal Process [BEP-1], Scheme Request for Implementation [SRFI] and the IETF RFC Series [RFC-8729].

References

Copyright

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.

1 Like
2

Hello Fediverse,

This is call for feedback and comments on the initial Fediverse Enhancement Proposal (FEP):

FEP-a4ed: The Fediverse Enhancement Proposal Process.

Summary:

A Fediverse Enhancement Proposal (FEP) is a document that provides information to the Fediverse community. The goal of a FEP is to improve interoperability and well-being of diverse services, applications and communities that form the Fediverse.

This document describes the scope, format and process of publishing Fediverse Enhancement Proposals.

This is something @lain, @cjs and myself worked on during the ActivityPubConf 2020 Hackathon (see Fediverse Enhancement Proposal (FEP)).

This initial FEP (FEP-a4ed) defines the format of a FEP and the process of publishing a FEP.

Community peer-review

The FEP publishing process is a peer-review system where you are the peers! Your comments are extremely valuable and an essential part of the process. If you have questions, comments or doubts please post. If you think this is a good idea, pleas also express your support.

Thanks!

4 Likes
3

There is a newer draft of the IETF inclusive language document than the one mentioned. It is at https://tools.ietf.org/html/draft-knodel-terminology-04

Additionally there is a repo where input for future drafts are collected: https://github.com/ietf/terminology

1 Like
4

Thanks! I will update the reference.

It would be even better to reference a finalized and stable document. Do you know if/when this document will be finalized? Or an other document in similar spirit?

5

I PR’ed to the repo (dark patterns --> deception patterns) and contacted Mallory Knodel:

We shall see the eventual fate of this work, but for now we do keep it up to date at this link: https://tools.ietf.org/html/draft-knodel-terminology

It is now on version 4 and probably isn’t quite done evolving. Linked within the latest version is a github repository unofficially
maintained by the general area and chair of the IETF (for now).

That link redirects to latest draft. The repo README has a list of other references, but the IETF doc looks the most evolved.

6

The draft says “A Fediverse Enhancement Proposal can be submitted by individuals or groups of individuals (authors) by creating a pull request to the FEP repository.” without specifying what “the FEP repository” is. I assume it is https://git.activitypub.dev/ActivityPubDev/Fediverse-Enhancement-Proposals/ but that gitea instance does not allow creating accounts (OpenID may work, but I have no OpenID identity provider that I know of at the moment).

2 Likes
7

@Claire I think for now it might be best just to make a new post on the forums with the text of the proposal?

8

I’ve opened up registration requiring e-mail confirmation. Emails should be sent by the server successfully now, but let me know if I need to manually activate the account for you.

2 Likes
9

That is correct. It was left implicit as the exact location was not yet set when writing. I think it can be made explicit now.

:tada: Thanks @cjs!

@Claire, does that work for you and resolve the issue?

I’d prefer if the exact file containing the proposal would be submitted. Posting on this forum would require extracting the Markdown (and meta-data) which I don’t think can be reliably done.

FEPs should be as easy to submit as possible and I would be open to other means of submission. For example:

  • Mirror the FEP repository on a popular Git-thing (e.g. GitHub) and also accept submissions there. The list of “endorsed” mirrors where submissions are accepted could be kept in a MIRRORS file in the FEP repository.
  • Accept submission by e-mail.

What are thoughts on a GitHub mirror or accepting submissions by Mail? (CC: @cjs, @lain)

10

Yeah, that works, opened a PR!

1 Like
11

I don’t know if it is better, but this link also tracks the IETF terminology doc https://datatracker.ietf.org/doc/draft-knodel-terminology/ (found via the W3C Internet Diversity CG which also has a Manual of Style with terminology suggestions).

12

A small update to FEP-a4ed just got merged. I hope this addresses the issues raised here. Quick summary:

  • Identifiers are now only 4 characters long (FEP-a4ed instead of FEP-a4edc7b). Slightly more memorable at a probably acceptable chance of collision.
  • Updated IETF Terminology draft to latest version (thanks @aschrijver)
  • Add a SUBMISSION_METHODS file to the root of the repository that includes the exact address of the repo and how to submit a proposal. This addressed the issue brought up by @Claire and at the same time allows the repo to be moved if ever necessary.

See the pull request for a diff: https://git.activitypub.dev/ActivityPubDev/Fediverse-Enhancement-Proposals/pulls/5

Some notes on the proposal status (as an illustration how submission process works):

  • It has been 46 days since FEP-a4ed was submitted (16th October 2020).
  • The initial draft period lasts for at least 60 days - until the 15th of December 2020.
  • On the 15th of December (or shortly after) I will request final comments on the proposal from you, the community. If there are no objections the propsoal will be finalized (receive status FINAL 14 days after - on the 29th of December)

The submission process takes a bit of time. The hope is that such a long time allows comments, suggestions and objections to be made without haste.

Personally, I am happy with the pace. The submission has not required constant attention from me and the work involved is reasonable.

1 Like
13

Nice work!

I think what’s still missing is what happens when things get FINAL. We have created something authoritative now, right? So that should be advertised on a prominent location preferably. I wonder about the current location being most suitable for that. I see git.activitypub.dev more as the workspace for FEP’s, and ideally, maybe FINAL FEB’s should be mentioned on activitypub.rocks landing page (though just linked to the repo with some info to it, that would be enough imho). Activitypub.rocks is #1 search result for ActivityPub and authoritative for the spec (besides the W3C, of course).

Also a topic with pointers and explainer might be permanently pinned to the top of this forum: “FEP’s: Wanna enhance the Fediverse? Here’s how the process works”

Edit: Oh, and imho the README should have a list or table of FEP’s in the repo, with link + brief description + status.

Some other feedback:

  • In Readme: “[After submission] you are now required to 
” and in FEP-a4ed “Authors are responsible 
”. I find the latter a better, more friendly description.
  • But what if someone started with good intention, FEP accepted, then slacks off in doing community outreach, asks for finalization, and after 2wks
 it becomes FINAL?

I am not familiar with FEP processes, but the last point may mean that hardly anyone noticed the FEP in the first place, and the FEP is of little value or detrimental to the quality of the process itself. Maybe there should be an additional step, where ‘the community’ feedback must be collected in the repo (e.g. as issue comments), even if to explicitly state “I stand behind this proposal” which is as valuable as discussions (especially when coming directly from fedi app maintainers).

Additionally either the FEP repo or activitypub.rocks or both might keep track of projects that have actually adopted / incorporated / implemented the FEP, which serves to demontrate its usefulness, and is both encouragement for others to adopt, as well as providing reference material (e.g. example code) for doing so.

14

Hello,

I created a new topic to host this discussion so it provides:

  1. a direct link to the repository entry
  2. a clean first post to host the future final version

I described the whole thing in About the Fediverse Enhancement Proposals.

1 Like
15

Absolutely. The idea was to first concentrate on the FEP documents itself and once it is in half-way decent form allow it to be presented in a nicer format. The document structure of FEPs was intentionally made easy to use from static-site generators. Some ideas on how and where to present FEPs in a nicer format:

  • library.activitypub.dev (cc @cjs)
  • activitypub.rocks: I’m all for adding FEPs there as well. I can submit a patch that makes haunt read FEPs and display them. However, who controls activitypub.rocks? Where and who hosts the site? Who decides what goes on there? And why not move git.activitypub.dev to git.activitypub.rocks? I think this should be forked to a topic for itself.

Props to @how for doing this.

This is something that can be very well be done by a static-site generator (or similar) and I am a bit reluctant to add it, as it does add considerable maintenance burden.

Ok, if we concentrate on doing this in a nice presentation of FEPs (e.g. library.activitypub.dev) and revisit index in README after?

:+1: done (https://git.activitypub.dev/ActivityPubDev/Fediverse-Enhancement-Proposals/pulls/6)

The default path is: DRAFT -> WITHDRAWN. And if interest in a proposal fades this is what would happen.

There is a lot of room for interpretation what is required for a proposal to be come final. FEP-a4ed says:

  - If there are no community objections within 14 days and the authors can show that they have initiated sufficient awareness and discussion of the proposal, an editor will set the status of the submission to `FINAL`.

The “burden-of-proof” lies with the author but what exactly is “sufficient awareness and discussion” is vague.

I hope a general understanding of what this means will develop naturally and we do not have to specify strictly the form and medium of discussion.

I’d suggest leaving it out of FEP-a4ed. In the future when we have tested the waters and seen what kind of discussions work, we might have a FEP-6c17: Best Practices for Initiating Discussion and Collecting Feedback on a FEP proposal. What do you think?

I invite you to consider yourself familiar with the process. :slight_smile:

There should not be much magic to it. The goal of FEP-a4ed is to understandably and correctly describe the process.

1 Like
16

Yes, that would also work if the README contains a clear reference to the list. Agreed.

Super idea.

Woot, thx   :partying_face:

17

Some remarks regarding FEP-f1d5: NodeInfo in Fediverse Software

The discussion of a possible security issue took place in a toot, and was followed-up on the forum, where - in this situation - it may be decided that this should not be documented in the FEP (as it is arguably a ‘security-by-obscurity’ issue that makes matters worse), BUT


The issue was a valid point that was brought up, and the decision not to include is possibly made somewhere deep in a long forum discussion thread. Not only should the original author be aware of it, but any other AP implementer should too.

Therefore 2 things may be part of the FEP document format:

  • A list of open issues, or rather decision points, where the outcome may be documented too e.g.: “We’ll avoid security-by-obscurity and include version information”
  • A link to the forum discussion topic / post where the decision was argumented and taken.
18

My personal vote is for the second option, for FEPs to link to:

1 Like
19

@cjs yes, that would be easiest maintenance-wise, and I think that this should be included in the FEP template, imho.

On the other point my experience is that discussion threads (such as this one with now 18 comments, or the Followers Sync FEP with 41 posts) are so easily TL;DR’ed, where they just respond to the most recent comment. You could say it is their fault then if they missed an open issue or decision in parsing the history of the thread. This saves the author some time, but shifts the burden to each and every reader.

The authors are probably most deeply aware of all ins and outs of the FEP, and are responsible for the collection of feedback already. Part of that might include providing this summary of open issues / decision points that allow readers to drill into the subject matter quickly.

Right now the issue tracker in the FEP repo is unused. The workflow might be that - as soon as an open issue pops up in discussion - someone (e.g. the author) creates a FEP-related issue, with an appropriate label, and maybe a user assignment indicating who is responsible for dealing with it. So for example:

FEP-f1d5: Include software.version in NodeInfo?   [decision]

Assigned to: @cjs
Discussion: https://socialhub.activitypub.rocks/t/fep-f1d5-nodeinfo-in-fediverse-software/1190/4

@macgirvin proposed to exclude software.version from NodeInfo because inclusion might pose a security issue.

The issue need not be larger than that. Discussion is on the forum. Once a clear agreement is reached the issue is updated with a [resolved] label and some text, then closed. Before the FEP enters finalization stage the Issues should be added to References section (or a separate section just for issues).

(Note that you could also create individual labels for each FEP, and then there’s no need to create a list, but instead you include the url to the filtered issues on that label in References section)

20

Sure, this would work. There should be an easy navigation from the static site to the markdown doc to PR to in the repo then.

I guess in my most recent comments above, it indicates there’s already a need for this, but in a slightly more specific and practical manner (if y’all agree with that feedback, that is).