165 lines
8.0 KiB
Markdown
165 lines
8.0 KiB
Markdown
# 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:
|
||
|
||
|
||
Add the name of your new parameter to the list at the constructor and initialize it as desired:
|
||
|
||
|
||
At the end of the class, add the corresponding getter and setter. It is very important that they are documented!
|
||
|
||
|
||
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).
|
||
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
Don't forget to look in the bottom-right corner, there you always find the instructions, warnings, errors, announcements...
|
||
|
||
|
||
|
||
Once you updated pycharm, go to File -> Settings... -> Plugins and search for _GitLab Merge Request_ and press Install.
|
||
|
||
|
||
|
||
### 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:
|
||
|
||
|
||
|
||
Click on _Clik to discover servers_ and select the gitlab.concordia.ca.
|
||
|
||
|
||
|
||
Observe that in the top-right corner of the tab, the message has changed from _No Repository_ to _Repo: /Guille/libs_.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
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!
|
||
|
||
|
||
|
||
|
||
|
||
### 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.
|
||
|
||
|
||
|
||
A window will appear with the information of the request:
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
Now pull (blue arrow), and delete the branch.
|
||
|
||
|
||
|
||
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.
|