From 7629f644209480e5e4d6ba265b466645e6bca648 Mon Sep 17 00:00:00 2001 From: Fabio Bonelli Date: Wed, 26 Aug 2026 09:13:14 +0200 Subject: [PATCH] doc(spec): deprecate the `features` key longDescription already allows basic markdown including bullet points and can hold the same content. Typically `features` is poorly maintained and filled only to satisfy the validator. The main description can also detail the features better, with a longer explanation and rich text. --- docs/standard/example/publiccode.minimal.yml | 3 --- docs/standard/example/publiccode.yml | 5 ----- docs/standard/forks.rst | 10 ++++------ docs/standard/schema.core.rst | 16 ++++++---------- 4 files changed, 10 insertions(+), 24 deletions(-) diff --git a/docs/standard/example/publiccode.minimal.yml b/docs/standard/example/publiccode.minimal.yml index 10a2504b..bba0dd83 100644 --- a/docs/standard/example/publiccode.minimal.yml +++ b/docs/standard/example/publiccode.minimal.yml @@ -21,9 +21,6 @@ description: is and why one should need it. We can potentially have many pages of text here. - features: - - Just one feature - legal: license: AGPL-3.0-or-later diff --git a/docs/standard/example/publiccode.yml b/docs/standard/example/publiccode.yml index bf927648..208942c3 100644 --- a/docs/standard/example/publiccode.yml +++ b/docs/standard/example/publiccode.yml @@ -53,11 +53,6 @@ description: documentation: "https://read.the.documentation/medusa/v1.0" apiDocumentation: "https://read.the.api.doc/medusa/v1.0" - features: - - Very important feature - - Will run without a problem - - Has zero bugs - - Solves all the problems of the world screenshots: - img/sshot1.jpg - img/sshot2.jpg diff --git a/docs/standard/forks.rst b/docs/standard/forks.rst index f09fbc76..5cc1164c 100644 --- a/docs/standard/forks.rst +++ b/docs/standard/forks.rst @@ -83,8 +83,8 @@ different repository. Parsers should expect and analyze other differences in ``publiccode.yml`` between variants of the software. Specifically -``description/features`` is designed to be compared across variants to -identify and show user-visible differences. +``description/longDescription`` is where a variant describes its +user-visible differences from the software it is based on. .. _authors-1: @@ -105,7 +105,5 @@ least: Moreover, authors **SHOULD** evaluate the following changes: -- add the features that differentiate the variant to the - ``description/features`` key. Existing features **SHOULD NOT** be - edited or removed from this list unless they have been removed from - the variant, to allow parsers to easily compare feature lists. +- describe the features that differentiate the variant in the + ``description/longDescription`` key. diff --git a/docs/standard/schema.core.rst b/docs/standard/schema.core.rst index 565a3c81..ae1cf12c 100644 --- a/docs/standard/schema.core.rst +++ b/docs/standard/schema.core.rst @@ -534,11 +534,11 @@ Whichever the format for the documentation, remember to make its source files available under an open license, possibly by committing them as part of the repository itself. -Key ``description/[lang]/features`` -''''''''''''''''''''''''''''''''''' +Key ``description/[lang]/features`` (*deprecated*) +'''''''''''''''''''''''''''''''''''''''''''''''''' - Type: array of strings -- Presence: mandatory (for at least one language) +- Presence: optional This key contains a list of software features, describing what capabilities the software allows to do. The audience for this text @@ -547,13 +547,9 @@ software. The features should thus not target developers; instead of listing technical features referring to implementation details, prefer listing user-visible functionalities of the software. -While the key is mandatory, there is no mandatory minimum or maximum -number of features that should be listed in this key. - -The suggested number of features to list is between 5 and 20, depending -on the software size and complexity. There is no need for -exhaustiveness, as users can always read the documentation for -additional information. +This key is deprecated, describe the main features of the software in +``description/[lang]/longDescription`` instead, for example as a +bullet point list. Key ``description/[lang]/screenshots`` ''''''''''''''''''''''''''''''''''''''