How to Contribute

Great to see you here! There are many ways to contribute to CoFI.

Reporting issues

Bug reports and feature requests are welcome. Please search before lodging an issue at our Github repository.

Code contribution

Thanks for making cofi better through coding! You don’t have to know all the details in order to contribute. If you feel confused and are unsure where to start, don’t hesitate to contact us via GitHub issues or Slack.

Here is a general flowchart for code contribution, including preparation, editing and submitting stages:

        %%{init: {'theme':'base'}}%%
flowchart LR
    subgraph PREPARATION [ ]
        direction TB
        fork(fork repository)-->clone(create local clone)
        clone-->env_setup(environment setup)
    end
    subgraph EDIT [ ]
        direction TB
        code(start coding)-->commit(commit as needed)
        commit-->push(push to your own fork)
    end
    subgraph SUBMIT [ ]
        direction TB
        pr(create pull request)-->modify(edit based on our comments)
        modify-->commit_push(commit and push)
        commit_push-->merge(we merge it once ready)
        pr-->merge
    end
    PREPARATION-->EDIT
    EDIT-->SUBMIT

    

1. Fork and clone respository

Click to hide / show

1. Navigate to the GitHub repository (cofi, or cofi-examples if you’d like to add or edit things in the example gallery)

2. Click the “Fork” button on top right of the page (followed by a confirmation page with a “Create fork” button)

3. Now you’ll be redirected to your fork of cofi, which is like a branch out in your namespace. (And later you will see it merges back when your pull request is approved)

           %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': false}} }%%
     gitGraph
       commit
       commit
       branch your_own_fork
       checkout your_own_fork
       commit
       commit
       checkout main
       merge your_own_fork
       commit
       commit
       

4. The fork now stays remotely on GitHub servers, what’s next is to “clone” it into your computer locally:

   $ git clone https://github.com/YOUR_GITHUB_ACCOUNT/cofi.git
   $ git remote add upstream https://github.com/inlab-geo/cofi.git
   $ git fetch upstream
   

   replacing YOUR_GITHUB_ACCOUNT with your own account.

5. If you are working on documentation, then remember to update the submodule linked to cofi-examples:

   $ cd cofi
   $ git submodule update --init
   

2. Environment setup

Click to hide / show

The environment setup is different depending on your purpose:

• If you are going to work on adding new forward examples, then make sure you have CoFI installed in the usual way.

• If you are going to work on adding/linking new inversion tool, or looking to add features or fix bugs in the library core, then try to prepare your environment to have dependencies listed in this environment_dev.yml file. It’s easy to set this up using conda under your local clone:

  $ conda env create -f envs/environment_dev.yml
  $ conda activate cofi_dev
  $ pip install -e .
  

• If you’d like to edit the documentation, then get the dependencies listed in this requirements.txt file. Set up this with pip:

  $ pip install -r docs/requirements.txt  # in a virtual environment
  $ pip install -e .
  

3. Coding / editing

Click to hide / show

Quick reference for working with the codebase:

To install:

pip install -e .

To test:

coverage run -m pytest

To auto-format:

black . or black --check . to check without changing

Additionally, we have some guidance on the following scenarios:

• New forward example

• New inversion tool

• Editing CoFI core

• Editing documentation

• Make a release

Again, don’t hesitate to ask us whenever you feel confused. Contact us via GitHub issues or Slack.

4. Testing your code

Click to hide / show

When you submit a pull request, an automatic testing job will be triggered on GitHub.

If you’d like to test your changes locally,

1. Follow instructions here to set up environment if you haven’t done so yet.

2. Run all the tests with

   $ pytest tests
   

3. Check the test coverage with

   $ coverage -m pytest tests; coverage report; coverage xml
   

   We require contributors to add your tests to ensure 100% test coverage.

5. Commit, push and pull request

Click to hide / show

The git commit operation captures the staged changes of the project.

The git add command is how you add files to the so-called “staging” area.

Therefore, a typical pattern of commiting a change is:

$ git add path1/file1 path2/file2
$ git commit -m "my commit message"

Please note that we aim to use Angular style commit messages throughout our projects. Simply speaking, we categorise our commits by a short prefix (from feat, fix, docs, style, refactor, perf, test and chore).

Once your changes are committed, push the commits into your remote fork:

$ git push

Open the remote repository under your GitHub account, you should be able to see the new commits pushed.

Now that you’ve finished the coding and editing work, look for the “Contribute” button -> “Open pull request”, write a description and continue as prompted.

Once your pull request is submitted, we are able to see it and will work our best to review and provide feedback as soon as we can. Thanks for all the efforts along the way of contributing! 🎉🎉🎉