doc(spec): deprecate the features key

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
 

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

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.

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``
 ''''''''''''''''''''''''''''''''''''''