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 hub 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.

## Requesting a merge to the main branch
### Add a plugin
First, it is required to install a plugin for such purpose. We recommend [GitLab Merge Requests](https://plugins.jetbrains.com/plugin/18689-gitlab-merge-requests), 
but you are free to choose the one you prefer. In order to install the plug, be sure that you have the latest pycharm version. 
Go to Help -> Check for Updates... It will ask you to Update the new version, click on Update and Restart and follow the instructions.

![update pycharm](./docs/img_contributing/img_9.png)

Don't forget to look in the bottom-right corner, there you always find the instructions, warnings, errors, announcements...

![pycharm announcement](./docs/img_contributing/img_10.png)

Once you updated pycharm, go to File -> Settings... -> Plugins and search for _GitLab Merge Request_ and press Install.

![pycharm plugins](./docs/img_contributing/img_11.png)

### Select the project
This step needs to be done only the first time.

Once the plugin is installed, it will appear a new tab at the bottom list called Gitlab Merge Requests as in the image:

![new tab](./docs/img_contributing/img_12.png)

Click on _Clik to discover servers_ and select the gitlab.concordia.ca.

![new server](./docs/img_contributing/img_13.png)

Observe that in the top-right corner of the tab, the message has changed from _No Repository_ to _Repo: /Guille/libs_.

![new repo](./docs/img_contributing/img_14.png)

If you now click on Refresh Merge Request (see previous image), you will get a message asking for a token. As you don't have one yet, click on Create token.

![create token](./docs/img_contributing/img_15.png)

You will be sent to the gitlab repository to create a new token. Give a name to it and check all options. 
You are creating a token that has the same permits as your gitlab account has. 

![create token in gitlab](./docs/img_contributing/img_16.png)

A new personal access token will be created. Copy and paste it in the Access Token box.
A token is a personal and no-transferable key. Don't show it to anyone!

![copy token](./docs/img_contributing/img_17.png)

![paste token](./docs/img_contributing/img_18.png)

### Create merge request
Every time you want to send some changes to the main branch (merge your branch to the main one)
you will need to follow these steps.

Right clic on the blanc area and select + Create Merge Request.

![new merge request](./docs/img_contributing/img_19.png)

A window will appear with the information of the request:

![request info](./docs/img_contributing/img_20.png)

Clic on Assignees + and look for the project owner, in this case, Guillermo Gutierrez Morote.
Select him as assignee and clic OK.

This action will send a request for the merge. Now wait until this is accepted or rejected. You will receive an email to 
the email account you use for gitlab with the answer.

Once the changes are accepted, go back to the main branch by selecting the Git tab (bottom-left). Right clic on Master and select Checkout. 

![checkout master](./docs/img_contributing/img_24.png)

Now pull (blue arrow), and delete the branch.

![erase branch](./docs/img_contributing/img_26.png)

Now you have again the same version as in gitlab. For new changes, create a new branch and repeat the process.

## Documentation and authoring
There are 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 appear 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. This official documentation is under development and will be 
linked here as soon as it is available.