From 1e376f54c33d9439c433fd64314f0e29291cd437 Mon Sep 17 00:00:00 2001
From: Martchus <martchus@gmx.net>
Date: Sat, 5 Jan 2019 16:55:28 +0100
Subject: [PATCH] Document adding new fields

It is an easy task but it is also easy to forget something.
---
 CMakeLists.txt           |  1 +
 doc/adding-new-fields.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 doc/adding-new-fields.md

diff --git a/CMakeLists.txt b/CMakeLists.txt
index d77ac23..90c7ed5 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -169,6 +169,7 @@ set(TEST_SRC_FILES
 
 set(DOC_FILES
     README.md
+    doc/adding-new-fields.md
 )
 
 # meta data
diff --git a/doc/adding-new-fields.md b/doc/adding-new-fields.md
new file mode 100644
index 0000000..09f4a99
--- /dev/null
+++ b/doc/adding-new-fields.md
@@ -0,0 +1,31 @@
+# Adding a new field
+
+This document describes how to add support for a new field. From these instructions
+one can also deduce what places need to be adjusted when amending support for a field.
+
+## Support new field in tagparser library
+1. Check whether https://wiki.hydrogenaud.io/index.php?title=Tag_Mapping contains
+   a recommendation for the specific field to be added.
+2. Add the field to the enum `KnownField`.
+3. Adjust `lastKnownField` accordingly.
+4. Adjust `Tag::proposedDataType(KnownField field)` if it is not a text field.
+   Consider that this method might be overwritten in format-specific implementations
+   which might need adjustment as well.
+5. Add the format-specific IDs to the corresponding header files, e.g. `vorbiscommentids.h`
+   for Vorbis Comments.
+6. Add the field mapping to the `internallyGetFieldId(KnownField field)` and
+   `internallyGetKnownField(const IdentifierType &id)` methods of all formats which
+   should be supported.
+7. For ID3v2 tags add the mapping `convertToShortId()` and `convertToLongId()` if
+   possible.
+
+## Support new field in the tag editor application
+1. Add the field to the `KnownFieldModel` class.
+    1. Add the English denotation of the field to `KnownFieldModel::fieldName`.
+    2. Add the field to the constructor `KnownFieldModel::KnownFieldModel` which
+       composes the list of fields shown in the GUI and whether they are displayed
+       by default or not.
+2. Add the field to the `FIELD_NAMES` macro. It is used for the CLI's auto-completion
+   and `print-field-names`. Only use small letters (a to z) here. No whitespaces!
+3. Add the field to the `FieldMapping::fieldMapping` array used by the CLI. Be consistent
+   with 2.!
\ No newline at end of file