In the development documentation, mention that the parameters of the …

…'Quality-time' source need to be changed when adding new metrics or sources to the data model. Fixes #4278.

docs/src/changelog.md

@@ -8,6 +8,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 <!-- The line "## <square-bracket>Unreleased</square-bracket>" is replaced by the release/release.py script with the new release version and release date. -->
 
+## [Unreleased]
+
+### Deployment notes
+
+If your currently installed *Quality-time* version is not v4.2.0, please read the v4.2.0 deployment notes.
+
+### Fixed
+
+- In the [development documentation](https://quality-time.readthedocs.io/en/latest/development.html#adding-metrics-and-sources), mention that the parameters of the 'Quality-time' source need to be changed when adding new metrics or sources to the data model. Fixes [#4278](https://github.com/ICTU/quality-time/issues/4278).
+
 ## v4.2.0 - 2022-07-22
 
 ### Deployment notes

docs/src/development.md

@@ -145,15 +145,54 @@ Production code and unit tests are organized together in one `src` folder hierar
 
 #### Adding new metrics
 
-To add a new metric you need to add a specification of the metric to the data model. See the documentation of the [shared data model](software.md#shared-data-model) component for a description of the data model. Be sure to run the unit tests of the shared data model component after adding a metric to the data model, to check the integrity of the data model. Other than changing the data model, no code changes are needed to support new metrics.
+To add a new metric you need to make two changes to the data model:
+
+1. Add a specification of the new metric to the data model. See the documentation of the [shared data model](software.md#shared-data-model) component for a description of the data model and the different metric fields.
+2. Update the `metric_type` parameter of the `quality_time` source in the data model. You need to add the human readable name of the new metric to the `values` list of the `metric_type` parameter and you need to add a key-value pair to the `api_values` mapping of the `metric_type` parameter, where the key is the human readable name of the metric and the value is the metric key.
+
+Be sure to run the unit tests of the shared data model component after adding a metric to the data model, to check the integrity of the data model. If you forget to do step 2 above, one of the tests will fail. Other than changing the data model, no code changes are needed to support new metrics.
+
+Suppose we want to add a lines of code metric to the data model, to measure the size of software. We would add the metric to the `METRICS` model in `src/shared_data_model/metrics.py`:
+
+```python
+"""Data model metrics."""
+
+from .meta.metric import ..., Metrics, Tag, Unit
+
+...
+
+METRICS = Metrics.parse_obj(
+    dict(
+        ...
+        loc=dict(
+            name="Size (LOC)",
+            description="The size of the software in lines of code.",
+            rationale="The size of software is correlated with the effort it takes to maintain it. Lines of code is "
+            "one of the most widely used metrics to measure size of software.",
+            unit=Unit.LINES,
+            target="30000",
+            near_target="35000",
+            sources=["sonarqube"],
+            tags=[Tag.MAINTAINABILITY],
+        ),
+        ...
+    )
+)
+```
 
 #### Adding new sources
 
 To add support for a new source, the source (including a logo) needs to be added to the data model. In addition, code to retrieve and parse the source data needs to be added to the collector component, including unit tests of course.
 
 ##### Adding the new source to the data model
 
-To add a new source you need to add a specification of the source to the data model. See the documentation of the [shared data model](software.md#shared-data-model) component for a description of the data model. Be sure to run the unit tests of the shared data model component after adding a source to the data model, to check the integrity of the data model.
+To add a new source you need to make three changes to the data model:
+
+1. Add a specification of the source to the data model. See the documentation of the [shared data model](software.md#shared-data-model) component for a description of the data model and the different source fields.
+2. Update the `source_type` parameter of the `quality_time` source in the data model. You need to add the human readable name of the new source to the `values` list of the `source_type` parameter and you need to add a key-value pair to the `api_values` mapping of the `source_type` parameter, where the key is the human readable name of the source and the value is the metric source key (`cloc` in the example below).
+3. Add a small PNG file of the logo in [`components/shared_data_model/src/shared_data_model/logos`](https://github.com/ICTU/quality-time/tree/master/components/shared_data_model/src/shared_data_model/logos). Make sure the filename of the logo is `<source_type>.png`. The frontend will use the `api/v3/logo/<source_type>` endpoint to retrieve the logo.
+
+Be sure to run the unit tests of the shared data model component after adding a source to the data model, to check the integrity of the data model. If you forget to do step 2 above, one of the tests will fail.
 
 Suppose we want to add [cloc](https://github.com/AlDanial/cloc) as source for the LOC (size) metric and read the size of source code from the JSON file that cloc can produce. We would add a `cloc.py` to `src/shared_data_model/sources/`:
 
@@ -175,6 +214,28 @@ CLOC = Source(
 )
 ```
 
+Because cloc can be used to measure the lines of code metric, we need to add the cloc source to the list of sources that can measure lines of code:
+
+```python
+METRICS = Metrics.parse_obj(
+    dict(
+        ...
+        loc=dict(
+            name="Size (LOC)",
+            description="The size of the software in lines of code.",
+            rationale="The size of software is correlated with the effort it takes to maintain it. Lines of code is "
+            "one of the most widely used metrics to measure size of software.",
+            unit=Unit.LINES,
+            target="30000",
+            near_target="35000",
+            sources=["cloc", "sonarqube"],  # Add cloc here
+            tags=[Tag.MAINTAINABILITY],
+        ),
+        ...
+    )
+)
+```
+
 ##### Adding the new source to the collector
 
 To specify how *Quality-time* can collect data from the source, a new subclass of [`SourceCollector`](https://github.com/ICTU/quality-time/blob/master/components/collector/src/base_collectors/source_collector.py) needs to be created.
@@ -278,12 +339,6 @@ src/source_collectors/file_source_collectors/cloc.py:26: unused class 'ClocLOC'
 
 Add `Cloc*` to the `NAMES_TO_IGNORE` in [`components/collector/ci/quality.sh`](https://github.com/ICTU/quality-time/blob/master/components/collector/ci/quality.sh) to suppress Vulture's warning.
 
-##### Adding a logo for the new source to the data model
-
-Add a small PNG file of the logo in [`components/shared_data_model/src/shared_data_model/logos`](https://github.com/ICTU/quality-time/tree/master/components/shared_data_model/src/shared_data_model/logos). Make sure the filename of the logo is `<source_type>.png`.
-
-The frontend will use the `api/v3/logo/<source_type>` endpoint to retrieve the logo.
-
 ## Testing
 
 This section assumes you have created a Python virtual environment, activated it, and installed the requirements for each Python component and that you installed the requirements for the frontend component, as described [above](#developing).