Skip to content

Propose a new category

There are two ways. Pick the one that suits you.

A. Open an issue (no technical knowledge needed)

  1. Open a new issue and use the "New category" template.
  2. Tell us:
    • which list it belongs to (Topics or Forms),
    • a short English name and description, and an id in lowercase with hyphens (for example dance or workshops-skill-sharing),
    • for a Form: which object types it applies to (Event, Video, ...),
    • at least one matching category elsewhere, such as a Wikidata entry,
    • which software would use it.
  3. People can discuss it for about two weeks. Maintainers then accept or decline it.

B. Edit the files yourself (about five minutes)

A new category is a small addition to two files, both in plain text.

1. Declare it in the list file, for example categories/topics.toml (edit on Codeberg). The id goes in square brackets:

[dance]

2. Give it a name and a description in i18n/topics/en.toml (edit on Codeberg):

[dance]
name = "Dance"
description = "Dancing and dance culture."

Add both anywhere in the file, the build sorts them. That is all: the id (dance) becomes the category's web address, and the page, the lists and the translation project update by themselves.

For a Form the first file also says which object types it fits:

[workshop]
applies_to = ["Event", "Group"]

If you forget one of the two files or make a typo, the automatic check on your pull request tells you exactly what is missing.

Prefer the command line? This adds both entries for you:

python3 build.py --new topics dance "Dance" "Dancing and dance culture."
python3 build.py --new forms workshop "Workshop" "A hands-on session." --applies-to Event,Group

Why two files?

The first file decides which categories exist. Because web addresses are permanent, creating a category should be a deliberate step that reviewers see. The second file holds the words, which translators work on. A typo in the words can never create a category by accident.

What makes a good category

  • A Topic makes sense for any kind of object, not only one application. If it only makes sense for some object types, it is probably a Form.
  • The description says exactly what you mean, so that people from other applications understand it the same way.
  • A published category can never be removed or change its meaning, so we are careful with additions.

Links to matching categories elsewhere are optional and can be added later; see Add a mapping.