Installation

Please read carefully before you "Copy and paste", since some instructions only make sense for very specific use cases. The main options are between just installing or deveoloping the package.

Installation without intent to develop

We do not have a pypi package yet, but the closest thing is to instruct pip to download directly from github. You do not have to checkout the repo to do so but only run the script:](https://github.com/MPIBGC-TEE/bgc_md2/actions/workflows/test_debian_pip_install_github.yml) This also works on windows in wsl2. This installation is tested by a workflow (which before running pip also installs some debian packages that you might want to check out from the workflow) To install directly from github, we provide a branch without history and some of the larger examples (automatically from the master).

Installation for developer

For developers who work with CompartmentalSystems, LAPM, ComputabilityGraphs and testinfrastructure simultaneously:

• Clone the repository and its submodules: Note: If you have forked the repository you probably want to put your forks ulr here. You can of course install the original but especially if you do so using setuptools develop mode to see the effects of your changes on the installed package you probably want to install from your fork.

  • If you do not have a bgc_md2 repo yet:

    git clone --recurse-submodules https://github.com/MPIBGC-TEE/bgc_md2.git

  • If you already have a bgc_md2 repo (and want to keep it):

    • Pull the changes in bgc_md2 and the submodules simultaneuously:

      git pull --recurse-submodules
      

    • Make sure that the submodule folders in src are not empty.

      git submodule init
      git submodule update
      

• Run the tests.

  cd tests
  ./run_tests.py
  

  (on MS-Windows replace the last line with)

  python run_tests.py
  

  If you can run this script successfully, you have a working installation of bgc_md and can run all functions.

Take a look at the workflow and the install script it calls.
[![test_debian_pip_install](https://github.com/MPIBGC-TEE/bgc_md2/actions/workflows/test_debian_pip_install.yml/badge.svg)](https://github.com/MPIBGC-TEE/bgc_md2/actions/workflows/test_debian_pip_install.yml)

• Working with the installation:

  • pulling: Since you will nearly always pull with the --recurse-submodules flag
    consider creating an alias

    git config alias.spull 'pull --recurse-submodules'
    

    which enables you to say git spull to achieve the same effect

  • Tips to work with git submodules:

Documentation

• The latest build of the package documentation can be found here:.

Contribution

Green master

We try to keep the master green and develop new features or bug fixes in short lived branches that are then merged back into the master https://nvie.com/posts/a-successful-git-branching-model/ See also https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell

• Example workflow to work on a feature branch iss26-non-importable-models you are asked to review
  • git branch -a (shows all branches including remotes)
  • git checkout --track origin/iss26-non-importable-models (creates a local copy that you can test)
• Example to create your own feature branch (here to fix an issue )
  • git checkout -b iss53

To merge into the master:

• run the testsuites
• merge into the branch test
• merge test into master

The (github) workflows run the testsuites. This is an additional protection against forgotten files or other idiosycracies of your setup, that let the testsuites succeeed locally but brake for other users.

Binder

The branch used for the installation on binder is automatically created from master or test by a script. It has no history and is not intended to be ever merged back.