#159 Code sanitisation (Updated)

docs/contributing/contributing.md

@@ -5,11 +5,72 @@ description: Guide on how to contribute to this project
 # How to contribute
 
 First off, thanks for taking the time to contribute!
+We use GitHub as our main collaboration platform. Please work from the `development` branch, create small feature branches, and open focused pull requests. Follow Conventional Commit messages (e.g., `feat:`, `fix:`, `docs:`), format Python code with Black, and add tests where needed. Never merge your own PR—wait for review and address all comments (including AI reviewer suggestions). Use Issues and Projects to track tasks and discussions.
+
+> This project requires Python 3.11. Do not use Python 3.12 or newer, as it may cause dependency incompatibilities, build failure or runtime errors
+
 
 ## General Feedback
 
 If you have a general feedback about our project, please do not open an issue but instead please fill in this [form](https://forms.gle/LRUq3vsFnE1QCLiA6)
 
+## Fork & branch processing
+
+First fork the origin repository to your own github repository, then clone the repository to your local computer.
+
+```bash
+git clone https://github.com/Your Account name/clima.git
+cd clima
+```
+
+Set up the upstream repository and check the output repositories.
+
+```bash
+git remote add upstream https://github.com/CenterForTheBuiltEnvironment/clima.git
+
+git remote -v
+```
+
+The terminal should output a list:
+
+- `origin → your Fork repository`
+- `upstream → origin repository`
+
+Check all branches.
+
+```bash
+git branch -a
+```
+
+The terminal will show a list of branches:
+
+```bash
+> * main
+  	remotes/origin/HEAD -> origin/main
+  	remotes/origin/development
+  	remotes/origin/main
+```
+
+Pull the development branch first, and if the terminal does not notice you that you should try the second command.
+
+```bash
+git checktout development
+
+git checkout -b development origin/development
+```
+
+Create a new branch in the development branch.
+
+```bash
+git checkout -b (your branch name)
+```
+
+Finally update and push to your repository branch if you modify the files.
+
+```bash
+git push origin (your branch name)
+```
+
 ## Code of Conduct
 
 Available [here](code_of_conduct.md)
@@ -35,6 +96,57 @@ pipenv run pre-commit run --all-files
 Hence, you will need to make sure that the code is formatted correctly before committing your changes; otherwise, the commit will fail.
 More information about pre-commit hooks can be found [here](https://pre-commit.com/).
 
+Install Black:
+
+We use ruff to enforce the code style and code formatting. You can run it with:
+
+```bash
+pipenv run ruff check .
+pipenv run ruff format .
+```
+
+To ensure that the code is formatted correctly, we use a pre-commit hook that runs Ruff before every commit.
+Run the following once to enable hooks in your local repo:
+
+```bash
+pipenv run pre-commit install
+# optional: run on all files
+pipenv run pre-commit run --all-files
+```
+
+Hence, you will need to make sure that the code is formatted correctly before committing your changes; otherwise, the commit will fail.
+More information about pre-commit hooks can be found [here](https://pre-commit.com/).
+
+```bash
+pipenv install black
+```
+
+Format your code before committing:
+
+```bash
+black .
+```
+
+## Testing
+
+Before submitting a Pull Request, please make sure:
+- All tests should pass.
+- You have installed project dependencies:
+
+```bash
+npm install
+
+pipenv install -r requirements.txt
+```
+
+From the root directory, run:
+
+```bash
+cd tests/node
+
+npx cypress run
+```
+
 ## Submitting changes
 
 Please send a Pull Request with a clear list of what you've done. Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:
@@ -45,6 +157,43 @@ $ git commit -m "A brief summary of the commit
 > A paragraph describing what changed and its impact."
 ```
 
+> Detailed requirements for submitting a PR are described in the [Pull Request Regulation](#pull-request-regulation) section below
+
+Classification of Common Commit Types:
+
+- `Main (Master)`: Stable branch, merge code that passes review and CI; merge and release every time,
+- `Develop`: Continuous Integration branch for daily integration with multiple collaborators.
+- `Feature/*`: feature development branch, cut out from main or develop, send PR to merge in after completing the feature.
+- `Fix/*`: defect repair branch, the same process as feature
+- `Release/*`: release preparation branch for freezing versions, fixing documentation, doing regressions and tagging.
+- `docs/*`, `chore/*`, `refactor/*`, `test/*`: documentation, miscellaneous, refactor, test type branches.
+- `Style`: style modification (does not affect the function): code formatting, space adjustment, naming rules unity.
+- `Refactor`: Code Refactoring: Refactor existing code to improve maintainability.
+- `Test`: Add or modify tests: add unit tests, integration tests, or modify test logic.
+- `Chore`: Build Configuration, Dependency Management, CI/CD Configuration Updates.
+- `Perf`: Performance Optimisation: Optimising code execution efficiency or memory usage.
+- `Ci`: CI Configuration Related: Changing Continuous Integration Configurations for Github Actions, Travis, Jenkins, etc.
+- `Build`: build system related: modify build scripts, packaging configuration.
+- `Revert`: Rollback Commit: Undoing a Previous Commit
+- `Security`: Security fixes, fixing security vulnerabilities, updating dependencies to prevent attacks.
+- `Deps`: Dependency Management: Dependency Management/Adding, updating, and removing dependency libraries
+- `Infra`: Infrastructure related: changes to development environments, containers, server configurations, etc.
+
+## Pull Request Regulation
+**Time to submit PR:**
+
+- User requirements/issues have been addressed or discussed in Issue and consensus has been reached.
+- Changes have been minimised (small steps/phased submission) to avoid "mega PRs".
+
+**The pull request should include the following information:**
+
+- **Description:** Provide a brief summary of the changes, related issues, and motivation. List any required dependencies. **Fixes # (issue)**
+
+- **Type of Change:** Bug fix (non-breaking); New feature (non-breaking); Breaking change; Documentation update.
+
+- **Testing:** Describe how you tested your changes and how we can reproduce them. Include test details if necessary.
+
+
 ## Thanks
 
 Thank you again for being interested in this project! You are awesome!

docs/documentation/tabs-explained/outdoor-comfort/utci-explained.md

@@ -18,3 +18,4 @@ The values are then converted into a scale assessing thermal stress, either beca
 <figure><img src="../../../.gitbook/assets/UTCI Index copia.png" alt=""><figcaption><p>UTCI heat stress index heatmap in the four conditions for <strong>Rome, ITA</strong></p></figcaption></figure>
 
 The UTCI is a useful tool to design the outdoor space, to maximize the number of comfortable hours. The designer can influence two factors out of the four driving outdoor comfort: radiant temperature (i.e. exposure to the sun) and wind speed (i.e. exposure to the wind).
+

docs/documentation/tabs-explained/psychrometric-chart/README.md

@@ -22,5 +22,4 @@ Moreover, data can be filtered by date, time, or one of the [Clima dataframe](..
 
 Learn more about the Psychrometric tab by watching the following video.
 
-{% embed url="https://youtu.be/VJ_wOHadVdw?si=iAcBQpq3IgCNY-H6&t=582" %}
-
+{% embed url="https://youtu.be/VJ_wOHadVdw?si=iAcBQpq3IgCNY-H6&t=582" %}

docs/documentation/tabs-explained/psychrometric-chart/psychrometric-chart-explained.md

@@ -28,4 +28,4 @@ The main application of the psychrometric diagram is in the design of large all-
 
 The diagram is applied whenever the humidity of a particular environment needs to be studied, for reasons of thermal comfort or for the preservation of valuable objects, such as in museums.
 
-<figure><img src="../../../.gitbook/assets/675px-Violino_Clisbee.jpg.webp" alt=""><figcaption><p>Stradivari Violin, stored under precise temperature and humidity conditions to prevent the valuable wood from warping.      Source: <a href="https://www.frammentirivista.it/il-clisbee-il-prezioso-violino-di-stradivari/">Frammentirivista</a></p></figcaption></figure>
+<figure><img src="../../../.gitbook/assets/675px-Violino_Clisbee.jpg.webp" alt=""><figcaption><p>Stradivari Violin, stored under precise temperature and humidity conditions to prevent the valuable wood from warping.      Source: <a href="https://www.frammentirivista.it/il-clisbee-il-prezioso-violino-di-stradivari/">Frammentirivista</a></p></figcaption></figure>

docs/documentation/tabs-explained/sun-and-cloud/README.md

@@ -26,4 +26,3 @@ This allows the user to identify climatic patterns in relation to the apparent s
 Learn more about the Sun and Clouds tab by watching the following video.
 
 {% embed url="https://youtu.be/VJ_wOHadVdw?si=mB2xNH57MWW_4CRR&t=447" %}
-

docs/documentation/tabs-explained/sun-and-cloud/cloud-coverage.md

@@ -18,4 +18,4 @@ As the Cloud cover is reported in tenths of coverage (i.e. 0 is 0/10 covered. 10
 | Cloudy (ABOVE range)    | <img src="../../../.gitbook/assets/Cloudy.2.png" alt="" data-size="line">       | 9                 |
 | Cloudy (ABOVE range)    | <img src="../../../.gitbook/assets/Cloudy.2.png" alt="" data-size="line">       | 10                |
 
-<figure><img src="../../../.gitbook/assets/CBEClima_San Francisco Intl AP_USA_cloud_cover_sun_tab.svg" alt=""><figcaption><p>Example cloud coverage graph for San Francisco, USA</p></figcaption></figure>
+<figure><img src="../../../.gitbook/assets/CBEClima_San Francisco Intl AP_USA_cloud_cover_sun_tab.svg" alt=""><figcaption><p>Example cloud coverage graph for San Francisco, USA</p></figcaption></figure>

docs/documentation/tabs-explained/sun-and-cloud/customizable-daily-and-hourly-maps.md

@@ -11,4 +11,3 @@ The chart above shows the [scatter plot](https://en.wikipedia.org/wiki/Scatter\_
 [Heat maps](https://en.wikipedia.org/wiki/Heat\_map) allow the intensity of values to be perceived through color palettes. These graphs are very helpful in seeing how magnitudes vary throughout the year.
 
 <figure><img src="../../../.gitbook/assets/Daily sun exa.png" alt=""><figcaption><p>Examples of daily graphs with different variables (from top left to bottom right): global horizontal radiation, global horizontal illuminance, zenith luminance, opaque sky cover</p></figcaption></figure>
-

docs/documentation/tabs-explained/sun-and-cloud/global-and-diffuse-horizontal-solar-radiation/README.md

@@ -12,3 +12,4 @@ Typical daily graphs showing the amount of energy gained from the sun have many
 * evaluating sustainable **renewable energy solutions** such as solar thermal or photovoltaic panels.
 
 The integral of the curves in the graphs is the total energy (in Wh/m²), supplied by the sun. Be careful in considering the [different types of solar radiation.](global-diffuse-and-normal-solar-radiation-explained.md)
+

docs/documentation/tabs-explained/sun-and-cloud/global-and-diffuse-horizontal-solar-radiation/global-diffuse-and-normal-solar-radiation-explained.md

@@ -13,4 +13,4 @@ $$
 
 ![Conceptual representation of Global Horizontal, Diffuse Horizontal and Direct Normal Solar Radiation](../../../../.gitbook/assets/picture3.png)
 
-![Measurement of Direct Irradiation on a horizontal and a normal plane](../../../../.gitbook/assets/picture4.png)
+![Measurement of Direct Irradiation on a horizontal and a normal plane](../../../../.gitbook/assets/picture4.png)

docs/documentation/tabs-explained/tab-summary/README.md

@@ -14,4 +14,3 @@ Learn more about the Climate Summary tab by watching the following video.
 
 <!-- markdownlint-disable-next-line MD034 -->
 {% embed url="https://youtu.be/VJ_wOHadVdw?si=H-93XRhh5Neuby_b&t=220" %}
-

docs/documentation/tabs-explained/tab-summary/clima-dataframe.md

@@ -29,4 +29,4 @@ All the variables in the new Clima dataframe are listed below.
 * [Wet-bulb temperature](https://en.wikipedia.org/wiki/Wet-bulb\_temperature)
 * [Elevation](https://en.wikipedia.org/wiki/Solar\_zenith\_angle)
 * [Azimuth](https://en.wikipedia.org/wiki/Solar\_azimuth\_angle)
-* [Saturation pressure](https://en.wikipedia.org/wiki/Vapour\_pressure\_of\_water)
+* [Saturation pressure](https://en.wikipedia.org/wiki/Vapour\_pressure\_of\_water)

docs/documentation/tabs-explained/tab-summary/climate-profiles-explained.md

@@ -15,4 +15,4 @@ On mouse hover, they display various statistical properties of the data:
 * 1st quartile
 * 3rd quartile
 
-![Climate Profiles for Jerusalem Center, ISRAEL](<../../../.gitbook/assets/image (2) (1) (1).png>)
+![Climate Profiles for Jerusalem Center, ISRAEL](<../../../.gitbook/assets/image (2) (1) (1).png>)

docs/documentation/tabs-explained/tab-summary/degree-days-explained.md

@@ -12,4 +12,4 @@ The base temperature does not necessarily correspond to the desired building int
 
 ![example deegree days for New York, Downtown Manhattan, NY, USA](<../../../.gitbook/assets/image (3).png>)
 
-![example deegree days for Palermo Boccadifalco Airport, ITALY](<../../../.gitbook/assets/image (1) (1).png>)
+![example deegree days for Palermo Boccadifalco Airport, ITALY](<../../../.gitbook/assets/image (1) (1).png>)

main.py

@@ -5,6 +5,7 @@
 from app import app
 from pages.lib.layout import banner, footer, build_tabs
 from config import AppConfig
+from pages.lib.global_element_ids import ElementIds
 
 server = app.server
 
@@ -22,7 +23,10 @@
 
 
 # callback for survey alert (dbc.Toast)
-@callback(Output("alert-auto", "is_open"), Input("interval-component", "n_intervals"))
+@callback(
+    Output(ElementIds.ID_MAIN_ALERT_AUTO, "is_open"),
+    Input(ElementIds.ID_MAIN_INTERVAL_COMPONENT, "n_intervals"),
+)
 def display_alert(n):
     return n == 1