💻 iMarina-load (Developer guide)

Prerequisites

You need Python 3.12.3 (or higher) version and git installed. To install them on Ubuntu, run this command:

 sudo apt install python3.12-venv gcc build-essential git -y

Installation

1.Clone repository of iMarina:

 git clone https://github.com/ICIQ-DMP/iMarina-load.git

Enter to folder of iMarina

 cd iMarina-load

2.Initialize a virtual environment (venv)

 python3 -m venv venv

3.Upgrade pip and install dependencies and requirements

 ./venv/bin/pip install --upgrade pip
 ./venv/bin/pip install -r requirements.txt

💻🧑‍💻 IDE Setup — PyCharm

🧩 1. Download and Install PyCharm

You can install PyCharm Community Edition (free) or Professional Edition (paid).

For manual installation on Linux using the .tar.gz package:

# Download the latest version from JetBrains community
wget https://download.jetbrains.com/python/pycharm-community-2024.2.tar.gz

Extract the file

 tar -xzf pycharm-community-2024.2.tar.gz

Move to /opt (recommended for global access)

sudo mv pycharm-community-2024.2 /opt/pycharm

2. Create a Shortcut (Alias)

To launch PyCharm quickly from any terminal, create an alias:

 echo "alias pycharm='/opt/pycharm/bin/pycharm.sh &'" >> ~/.bashrc
 source ~/.bashrc

Now you can open it by simply typing:

 pycharm

The alias will remain available even after restarting your terminal.

🌿 3. Clone the Project Repository (iMarina-load)

 cd /home/username/Desktop

 git clone https://github.com/ICIQ-DMP/iMarina-load.git

 cd iMarina-load

Then open the project directly in PyCharm:

 pycharm .
 pycharm
# all forms is correct

💡 iMarina-load Usage

Obtaining translations excels

By default, they are read from the input/ folder but you can change the location of these expected files with the following arguments:

--imarina-input /path/to/iMarina.xlsx      
--a3-input /path/to/A3.xlsx  
--countries-dict /path/to/countries.xlsx    
--jobs-dict /app/input/Job_Descriptions.xlsx

To start the program execute this command with argument –imarina-input:

./venv/bin/python src/main.py --step build --imarina-input ./input/iMarina.xlsx

You can either Download them manually from Sharepoint, or you can use the Dockerized OneDrive service to sync files from Sharepoint to your host computer automatically in the background.

💻 OneDrive service

The program will display a link and ask you to authenticate and paste the answered URL into the terminal.

  cd services/onedrive
  bash run.sh

After following the steps, OneDrive will be syncing the folder
Institutional Strengthening/_Projects/iMarina_load_automation/input
from Sharepoint into services/onedrive/data.

Add or change the necessary arguments to read from this new source, instead of input/, so that data consumed by the program is always updated.

You can leave OneDrive running so that the files are always in sync.

🐳 Docker basic info

Access the container shell:

 docker-compose run --rm app sh

🧪 Testing section

All tests are managed using pytest and are located in the tests/ directory.
The testing process ensures that all core functionalities work as expected before deployment.
For detailed testing setup, configuration, and automation through Docker or GitHub Actions, refer to the Programming standard document.

🧭 Git Branching Model

The project uses a two-branch model based on Git best practices:

master → stable, production-ready branch
develop → main branch for integrating and testing new features

🌱 Workflow

Pull the latest version of develop:

git checkout develop
git pull origin develop

Create a new branch for your feature or fix:
```
 git checkout -b feature/my-feature
```

After finishing your changes:

 git add .
 git commit -m "feat: add ......"

Push your branch to GitHub:

  git push --set-upstream origin feature/my-feature

Open a Pull Request (PR) (if necessary) on GitHub to merge into develop.
Once tested and approved, develop can be merged into master for release.

🛠️ Useful Commands

List all branches
```
 git branch -a
```
Switch between branches
```
 git checkout branch_name   
```

Delete a local branch

 git branch -d branch_name
#or
 git branch -D branch_name

Visualize branch history
```
 gitk --all &
```
Discard local changes
```
  git reset --hard
```
Update your branch with the latest develop
```
 git pull origin develop --no-ff
```

More info in Programming standard

Programming Standard