Allow extra section in package manifest

1 files changed, 23 insertions, 0 deletions

diff --git a/manifest-reference.md b/manifest-reference.md
index 0a68c6a..2c79a02 100644
--- a/manifest-reference.md
+++ b/manifest-reference.md
@@ -49,6 +49,8 @@ Every manifest file consists of the following sections:
     Dependencies only needed for tests
 - [*install*](#installation-configuration):
   Installation configuration
+- [*extra*](#additional-free-data-field):
+  Additional free data field
 
 
 [TOML]: https://toml.io/
@@ -479,3 +481,24 @@ By default only executables are installed, library projects can set the *library
 [install]
 library = true
 ```
+
+
+## Additional free data field
+
+Third-party tools can store their configuration inside the *extra* section.
+This section will never be evaluated by fpm itself, the only constraint imposed it that is has to be valid TOML.
+
+Since the format of this section is free, only recommendations are provided here for adding data to the *extra* section.
+
+1. Only use subtables, never add configuration data to the toplevel of the *extra* section.
+   Reasoning: different tools can avoid collisions of keynames by placing their data in separate subtables
+2. Use the concrete name of the tool rather than a generic name for the subtable.
+   Reasoning: different formatter or linter might use conflicting keywords in a *format* or *lint* subtable.
+   Also, users can tell from the table name which tool is preferred for usage with the project.
+3. Fpm plugins should use a subtable with their plugin name in the *extra.fpm* section to store their data.
+   Reasoning: following this convention provides the user of fpm plugins with one section to configure their used plugins.
+4. Use the fpm preferred style for keywords which is lowercase with dashes.
+   Reasoning: while there is no style check in this section, a consistent style in the whole manifest will make it easier for the user to understand the whole package manifest.
+
+Feedback for the recommendations above is very much welcome.
+If you have a tool that uses the *extra* section in the package manifest, feel free to post it in at the [fpm discussion board](https://github.com/fortran-lang/fpm/discussions).