How to create a FEP topic

:todo: use the Discourse API to autocreate the topic when the repository entry is created.

Staff members and @activitypub.hosts can create a topic in the #activitypub:fep category.

FEP-09ba: Sample FEP

For the purpose of illustration we imagine the following FEP:

  • title: Sample FEP
  • link to repository:

Process to create the FEP-09ba topic

  1. Copy the original FEP link from the repository
  2. Hit the image button and paste the link in the title field.
  3. Edit the resulting title to read FEP-e9ba: Sample FEP
  4. Edit the body to read source:
  5. Add the tags: fep , draft , fep-e9ba .
  6. Ensure category is #activitypub:fep
  7. Save edit
  8. Change ownership to the @system user
  9. Move any previous discussion to this topic or reference it

What you obtained

A new, properly referenced FEP topic is available that provides a direct link to the original FEP from the topic list (thanks to step 2) and can be further discussed in an obvious place.

Next Steps

  1. You can copy-paste the new topic URL to the Drafts section of the FEP Index.
  2. Keep an eye on the FEP status to adjust tags, and eventually publish the FEP.

When the FEP goes FINAL

Once the status moved to FINAL, the FEP is to be made available as a published page.

  1. Edit the initial post of the FEP-09ba topic
  • Copy-paste the actual raw content of the FEP on Codeberg
  • Replace authors by their handles there to avoid publishing email addresses and facilitate author contact
  • Replace the draft tag with final
  1. Once done, you can hit the … menu > wrench and choose the Page Publishing option: the page slug should look like .../pub/fep-09ba-sample-fep — publish it!
  2. Copy the published page link and update the FEP Index to move the FEP from the Drafts to the Final ones. More exactly: add the published page link to the Final section and move the original topic link from the Drafts section to this new link, with :speech_balloon: as an anchor.

In general, looking at previously published FEPs will help!

This is also a continuation of

Background I tried to follow the steps from

and got stuck on publishing. When I asked @aschrijver for advice, he pointed out that I probably lack sufficient permissions to publish. Furthermore, at this point the process was already time consuming (lots of manual steps), and I was not even halfway done.


As discussed in the link above, I still think having a nicer landing page for FEP listing Final FEPs would be beneficial. Both giving authors an incentive to reach the state final and offering less technical inclined people a place to start than the

Generally, this should lead to better visibility of FEP.

My proposal would be to use Codeberg pages together with automation through codeberg ci to achieve this. The goal would be to obtain a process that runs without further human input, but updates the pages automatically.

I believe @trwnh proposed something similar at one point.

Technical Question: Does somebody know a nice static site generator that fits the theme? We probably want some extra features from the markdown → html conversion such as generating tables of contents for the FEPs.

1 Like

We might consider ReSpec or BikeShed, both of which are tailored for writing specifications. Other than that Astro is a great site generator and comes with an official Docs theme (see their own docs). But there are a gazillion of them (I use Jekyll Just the Docs myself).

Hugo is the gold standard when it comes to things like this, generally and in my experience. It’s not the nicest to work with (ugh, Go templating), but it does at least have a very wide feature set. Chances are that, if you want to do it, Hugo supports it.

@helge indeed, you’re lacking privilege, which is not a technical issue. I proposed that you become a member of @fep.hosts but only @aschrijver replied, which I do not consider sufficient. The following bikeshedding concerning what better tool to use is not very useful, since it would, again, fragment the community. Anyway, static sites tooling preference does not sound like a useful discussion to have since there are hundreds and everyone has their favorite.

I agree with @helge that Codeberg CI could be used to automatically post a new topic here with the same content of the repository and maintain changes so that the FEP can appear both on Codeberg pages and here — with the added benefit that now, new topics from this category are announced on the Fediverse.

Eh, all that matters here is that someone picks something and it gets hooked up to Codeberg Pages and CI.

I don’t think it fragments community. The FEP documents are already at Codeberg, and the discussion on them is here at the forum. Codeberg Pages can be enabled within the same repository in a pages branch.

I’ve played around with BikeShed yesterday. First, converting FEPs to BikeShed would require a fair bit of work to migrate at least metadata and references. I’m unsure this could be automated or be done without manual steps. Similarly, one might need to spend time on customization to get a status “Final FEP”.

Second: Using a tool such as BikeShed, which creates a look similar to W3C specifications, would send a message. It makes everything appear more official. Is this something we want?

For me the goal of this Codeberg Pages would be to create something nice that can be used to present FEP to outside this community, i.e. something for people not working on FEPs but possibly working with FEPs. Looking like W3C might led us borrow some of the W3C’s prestige to be taken more seriously, but might come with expectations that we do not satisfy.

I think this is actually, what makes sense to explore here. Can we automate some things to simplify the FEP editorial work?


Agree that bikeshed and respec look more official (this might be subjective)

It could be a good choice for a living standard or vocab extensions

Maybe the socialhub logo and some text would make it clearer where the work is incubated

1 Like