city_retrofit/CONTRIBUTING_CENTRAL_DATA_MODEL.md

# How to create a class for the Central Data Model

This document explains the steps to follow if you want to contribute to the city data model by adding new classes or new attributes. 
Use this document after having a clear idea of how your data model should look like already integrated in the Central Data Model. 
Please, refer to the [cerclibs.pdf](https://liveconcordia.sharepoint.com/:b:/s/CERC-Next-GenCities-Platform/EfPNAGXexCFOju2sKBr6pNMBcwnvLin1Wio1Ahpfu4cxag?e=rhkdca)
to integrate your data model with the Central Data Model.

## Starting with the basics
-	Install all requirements and download the Libs project. [Here](WINDOWS_INSTALL.md) how to do it for windows. 
In order to maintain a good quality code, we will work in branches. New codes will need to pass quality standards before being accepted in the main branch.
-	Check and follow our [coding style](PYGUIDE.md)
-	Don’t forget to create unit tests and ensure that the old ones pass normally after your changes.
-	Imperative! Document your work using comments in the code and, if needed, adding text files with extended explanations.

If the code doesn't pass the quality review, it will be rejected.

## Adding new parameters to existing classes

Adding a new parameter is an easy task. Open the desired class, for example, CityObject:
![city object](./docs/img_contributing/img_5.png)

Add the name of your new parameter to the list at the constructor and initialize it as desired:
![new parameter](./docs/img_contributing/img_6.png)

At the end of the class, add the corresponding getter and setter. It is very important that they are documented! 
![getter and setter](./docs/img_contributing/img_7.png)

You will see that the name of the file (city_object.py) changes from white to blue. That means that your version is different 
from that one in the git. Once you finish doing your changes, you should commit and push them to your branch. The name of the file will turn back white.

## Creating a new class

Create a new class in the corresponding folder (if it does not exist, create a new folder ad hoc).
![new folder](./docs/img_contributing/img_0.png)
![new file](./docs/img_contributing/img_1.png)
![add to git](./docs/img_contributing/img_2.png)

And add it to git (the name of the file will turn from red to green).
Every new class must have:
-	A header with the following information:

```python

"""
My New Data Class module
SPDX - License - Identifier: LGPL - 3.0 - or -later
Copyright © 2022 Concordia CERC group
Project Coder Name of Project Coder name.project.coder@concordia.ca
"""
```

-	A brief explanation of what it is, what it does, what it can be used for, etc. under its name:

```python

"""
MyNewDataClass class
This class models this and does that
"""
```

-	All imported libraries together at the beginning.

![new class](./docs/img_contributing/img_3.png)

A data class contains properties that describe the data model. Therefore, it should be mainly composed by getters and setters. 
We would like to avoid having methods in the data classes. All those methods that could be done in the factories must be written there.
The properties can be divided into two groups, those that can be modified during the use of the model, and those that 
are set only once and stay unchangeable. The line that divides these to groups is sometimes difficult to draw. 
An example to get a taste of this difference could be the following. A building is formed by surfaces, the list of surfaces 
is something that defines the building and, for our purposes, is unchangeable. On the other hand, if one of our studies is 
to show the effect of the construction on the building demand, we may want to modify this during the run, so the construction 
becomes changeable. This is important because those parameters that are static (unchangeable), must be provided for the 
initialization and don’t have setter, while the others are initialized at None and do have setter:
 
It is important to highlight that all setters and getters (@property) must have comments to describe the parameters, as shown in the previous image.

![new class getters and setters](./docs/img_contributing/img_4.png)

Once you finish doing your changes, you should commit and push them to your branch. The name of the new files will change from green to white.

## Documentation and authoring
There can be two types of authors, that one who created the model and that one who coded it. If they are not the same person, 
in the headers of the classes must be just the name of the coder, who is the reference person to ask anything about the code,
and the one in charge of maintaining it, and interacting with the git.

The author of the data model will appear in the official documentation of the Insel4Cities platform. In those documents, 
a larger explanation of the data model should be also added.