New Espresso problem#

👋 Everyone is welcomed to contribute with their own forward code. We aim to reduce the barrier of contributing so don’t worry if you are not familiar with those technical stuff like git operations - we are here to help.

There are generally three steps involved in submiting your code:

In the following paragraphs, we are going to show you how to complete each of the steps above. Again, feel free to contact us when in doubt.

Get your own copy of Espresso#

  1. Open your browser and go to the Espresso repository.

  2. Ensure you have a GitHub account and it’s signed in. If not, click the “Sign Up” button on the top right and fill in the necessary information to sign up an account.

  3. Now click the “Fork” button on the top right.

    ../_images/contrib_fork.png
  4. Leave everything by default and click the green “Create fork” button.

    ../_images/contrib_fork2.png
  5. Now you will be redirected to your own “fork” of the Espresso repository.

    This fork is your own version of Espresso, and you can make changes however you want. We will later demonstrate that after you make your own changes, you are able to “contribute” back to the main repository.

    ../_images/contrib_fork3.png
  6. We will clone your fork into your local machine. Click the green “Code” button first, and then copy the content under the “HTTPS” tab.

    ../_images/contrib_fork4.png
  7. Clone your fork to somewhere in your computer.

    • For MacOS and Linux users, open your “Terminal” app, change your working directory into somehwere you’d like to place the Espresso code, then run the git clone command as following.

    • For Windows users, please install git first, and open “Git Bash” to run the following commands. In the steps afterwards, it’s always “Git Bash” when we refer to a “terminal” if you are on Windows.

    cd <path-to-espresso>
    git clone <url-you-copied-in-step-6>
    
  8. Open <path-to-espresso>/espresso folder with your favourite code editor. You will see a copy of Espresso in front of you, cheers ☕️!

Add your own Espresso problem#

  1. Let’s now ensure that you have a correct environment set up. Python >= 3.6 is required, and see this environment_contrib.yml file for a list of required packages.

    • Choose a Python environment manager first. mamba / conda is recommended as it can set up system-wide dependencies as well, but feel free to use the one you are most familiar with.

    • Python >= 3.6 is required.

    • If you use mamba / conda, run conda create -f envs/environment_contrib.yml under the project root folder. Otherwise, make sure you have the list of packages in environment_contrib.yml in the virtual environment with your preferred tool.

  2. Install Espresso core library - this enables you to access the base class for an Espresso problem EspressoProblem and some utility functions to help the development.

    Run the following in your terminal, with <path-to-espresso>/ as your working directory.

    pip install .
    
  3. Create a folder for your new contribution under contrib/<problem-name>, by running the following in your terminal:

    python <path-to-espresso>/tools/new_contribution/create_new_contrib.py <problem-name>
    

    Replacing path-to-espresso with your path to the espresso folder you’ve just cloned, and problem-name with your Espresso problem name, with lower case words connected by underscores (e.g. gravity_density, polynomial_regression).

  4. Navigate to folder <path-to-espresso>/contrib/<problem-name>, and you’ll see template files.

    ../_images/contrib_edit1.png
  5. Read instructions in the README.md file, and you will know what to do next 🧑🏽‍💻👩🏻‍💻👨‍💻

    1. You should already have all the “pre-requisites” installed if you’ve gone through the steps above.

    2. Check the boxes under “getting started”. These are pretty much all the things you’ve got to do to complete this contribution.

    3. When you’d like to perform a quick local test by running your own code, tips under “how to unit test your code” can be useful.

    4. When you think you’ve finished the coding, use scripts under “how to test building your contribution with cofi-expresso” to include your contribution into the package locally.

Submit your changes#

  1. It’s helpful to “commit” your changes when you have any progress. Feel free to make commits as often as necesary.

    • Use git add <file-name-1> <file-name-2> to choose which files you’d like to include in the following “commit”.

    • Use git commit -m "progress in xxx" to commit your changes.

    • Use git push origin <branch-name> to push your changes onto your GitHub fork, where <branch-name> is main by default.

    See also

    Check this cheatsheet for a good reference of using Git.

  2. After you’ve commited code changes and pushed your commits up to your fork, open your fork on GitHub https://github.com/<your-gh-account>/espresso in a browser.

  3. Find the word “Contribute” on top of the page, click it and choose the green “Open pull request” button. Follow the prompts and fill in necessary message you’d like us to know.

  4. Once your pull request is submitted, some automatic checks will be triggered. Rest assured - we will review your contribution, comment if necessary, and proceed to merge your contribution into our main repository when everything’s ready.

  5. Thanks again, for your contribution to open source 🌟