## Cheat sheet for working on your own project based on MnMS repository

This guide is relevant for MnMS users and developers if:
* one plans to develop her own scenario using the original features of MnMS while saving her code in a github private repository and beneficiting from the last updates made on the original repository
* one plans to develop custom/unofficial features for MnMS while saving her code in a github private repository and beneficiting from the last updates made on the original repository

Official developpers of MnMS working on approved features can directly work on a branch of the original MnMS repository. However, some sections of this guide can help the onboarding of new developpers.

### Create a private fork of the original MnMS repository

First step to have your code safely hosted on github is to create your fork of MnMS. As classic forks of public repositories are public, you can follow these steps to create a private fork and keep you code secret for the Internet. Note that if you want to make your science open, you can change the visibility of a private repository to public at any time.

1. Create a bare clone of the MnMS original repository

git clone --bare https://github.com/licit-lab/MnMS.git

2. Create a new private repository on Github (check this [guide](https://docs.github.com/fr/repositories/creating-and-managing-repositories/creating-a-new-repository) if required) and name it according to your needs, with a different name than MnMS to not mix up. We choose **MyMnM** for this guide.

3. Open a terminal, go to the location of your bare clone and mirror-push your it to your new MyMnMS repository.

cd MnMS.git
git push --mirror [e-mail]:<your_username>/MyMnMS.git

4. Remove the temporary local repository you created in step 1

cd ..
rm -rf MnMS.git

5. Clone you MyMnMS repository on your machine in the location of your choice (here we choose `~/Documents/Github_Project/`)

cd ~/Documents/Github_Project/
git clone [e-mail]:<your_username>/MyMnMS.git

6. Add the original repository as remote to fetch (potential) future changes. Disable push on the remote.

cd MyMnMS
git remote add upstream https://github.com/licit-lab/MnMS.git
git remote set-url --push upstream DISABLE

With `git remote -v` command in the terminal, you should see all your remotes: `origin` should designates your private fork and `upstream` should designates the original MnMS repo (check that push is well DISABLE for upstream!)

(Written from this [post](https://gist.github.com/0xjac/85097472043b697ab57ba1b1c7530274))

N.B.1: If new commits have been pushed on `develop` branch of the original MnMS repository, you can get them into you private fork with the following commands:

git checkout develop
git pull upstream develop
git push origin develop
git checkout feature/nameOfFeature
git rebase develop
git push origin feature/nameOfFeature --force-with-lease

During the rebase, you may have to solve the conflicts with your own code. Follow git instructions if this happens.

N.B.2: To commit and push your local modifs on your branch of you repo, you can follow these commands if you're working with someone else:

git stash 
git pull origin feature/nameOfFeature --rebase
git stash pop

Resolve the eventual conflicts. For each of the files you want to commit and push:

git add pathToFile

Commit and push:

git commit -m'Commit message describing your work.'
git push origin feature/nameOfFeature

If you're working alone on the repo, the pull command is not necessarily relevant.

### Install a new env for running code of your private fork

Working within environment is a good practice, and having a dedicated environment for you own code is preferable as you may need additional modules compared to the origin MnMS code.

1. As `develop` branch is the most updated one, checkout this branch and create+checkout your own working branch from it. If you plan to work on a new feature, you can name your branch `feature/nameOfFeature`. If you want to work on a new scenario/example, you can name your branch `scenario/nameOfScenario`. You'd better choose a meaningful name.

git checkout develop
git checkout -b feature/nameOfFeature

2. As we want to work within a dedicated conda env, change the name of the dev environment. Open the file `conda/dev.yaml` and change the line `name: mnms` to `name: MyMnMS`. Save the file.

4. Create and install the dev environment.

conda env create -f conda/dev.yaml
conda activate MyMnMS
python -m pip install -e .

You can install additional module whenever you want in this environment with conda or pip after having activated the environment. For e.g., to install the modules to be able to work in a jupyter notebook, do:

conda activate MyMnMS
conda install -c anaconda ipykernel notebook

5. MnMS requires HiPOP, which is the module for high performance shortest paths computation. Go back to `~/Documents/Github_Project/` and clone HiPOP repository. Similarly to MnMS repo, the most updated branch of HiPOP is `develop`so you can checkout it.

cd ..
git clone https://github.com/licit-lab/HiPOP.git
cd HiPOP
git checkout develop

6. Install the necessary modules to compile C++ code and wrap it to python. Then, install HiPOP.

conda install -c anaconda cmake
conda install pybind11 -c conda-forge
cd python
python install_cpp.py
python -m pip install .

7. Now, you should be able to launch simulations. You can test your installation by launching one of the examples provided in MnMS. For e.g.:

cd ../MyMnMS
python examples/manhattan_full_simulation/run.py

Alternatively, you can launch the tests with:

cd ../MyMnMS
pytest .