Contribute to CoFI#

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.

General Workflow#

Here is a general flowchart for code contribution, including preparation, editting 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

Fork and clone respository#

  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
  1. 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
    

    replacing YOUR_GITHUB_ACCOUNT with your own account.

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

    cd cofi
    git submodule update --init
    

Environment setup#

The environment setup is different depending on your purpose:

Coding / editting#

We have some guidance on the following scenarios:

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

Commit, push and pull request#

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 editting 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! 🎉🎉🎉

Coding in CoFI#

New forward example#

CoFI doesn’t have any forward solvers in the package itself. Instead, we manage all of our forward code as a part of the example gallery maintained in the cofi-examples respository.

Follow the instructions here for details on how to contribute to the example repository.

Our tutorials page is a good place to start learning about how to plug in an inversion problem in cofi. Furthermore, there are examples with increasing complexity presented in the example gallery page for you to learn from.

New inversion solver#

Thank you for your attempt in enriching cofi’s library pool.

To define and plug in your own solver backend, you minimally have to create a subclass of solvers.BaseSolver and implement two methods: __init__ and __call__. Additionally, add the name and class reference to our solvers tree under src/cofi/solvers/__init__.py so that our dispatch routine can find the class from the name specified in an InversionOptions instance.

Documentation in tutorials and API reference - BaseSolver provides further details and examples.

Follow the environment setup section to set up the package and commit, push and pull request section to raise a pull request.

We would also appreciate it if you write tests that ensure a good coverage under the file path tests.

Feature or bug fixes in cofi core#

A simple how-to guide for developing cofi core:

To (re-)build

rm -rf _skbuild; pip uninstall cofi -y; pip install -e .

To test

coverage run -m pytest; coverage report; coverage xml

To auto-format

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

Here we provide a mapping table to the parts of code related to each existing feature.

Table: feature mapping to code file#

Functionality

Code file path

BaseProblem

src/cofi/base_problem.py

InversionOptions

src/cofi/inversion_options.py

Inversion

src/cofi/inversion.py

InversionResult

src/cofi/inversion.py

solvers tree

src/cofi/solvers/__init__.py

solver dispatch function

src/cofi/inversion.py

BaseSolver

src/cofi/solvers/base_solver.py

validation for BaseProblem and InversionOptions objects

src/cofi/solvers/base_solver.py

Documentation#

It’s very easy to edit or write documentation for CoFI. Start by cloning our GitHub repository and setting up the environment, following instructions above - fork & clone and environment setup. Then head straight to the parts that you want to change, based on the mapping table below:

Table: documentation page mapping to file path#

Documentation page

File location

Home

docs/index.rst

Installation

docs/installation.rst

Tutorials (front page)

docs/tutorials/scripts/README.rst

Tutorials (tutorials content)

cofi-examples tutorials/tutorial_name.ipynb

Example gallery (front page)

docs/examples/scripts/README.rst

Exmaple gallery (examples content)

cofi-examples examples/example_name/example_name.ipynb

Frequently asked questions

docs/faq.rst

List of functions and classes (API)

docs/api/index.rst

API reference for BaseProblem

src/cofi/base_problem.py

API reference for InversionOptions

src/cofi/inversion_options.py

API reference for Inversion

src/cofi/inversion.py

API refernece for InversionResult

src/cofi/inversion.py

API reference for BaseSolver

src/cofi/solvers/base_solver.py

Change Log

CHANGELOG.md

Contribute to CoFI

dos/contribute.rst

To change the configuration of this documentation, go change the content in file docs/conf.py.

To adjust the styling of pages, modify things in docs/_static/style.css and docs/_templates.

To test the changes, go to docs directory, run make html and open the file docs/_build/html/index.html in your browser to see the changes.

reStructuredText

All of the documentation (except for the ChangeLog part), including API references, use the reStructuredText format. This is a textual file format that tends to be more powerful compared to markdown.

For the purpose of CoFI documentation, a good resource for reStructuredText syntax is the sample project (we link to the Book theme, the one this documentation uses), with the sources here to refer to.