Creating a new Espresso problem
Contents
Creating a 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:
Download - get a copy of Espresso
Itâs important to note that after youâve uploaded your contribution, you can still edit it with the same âpull requestâ workflow.
In the following paragraphs, we list out detailed steps on how to contribute a new example. Again, feel free to contact us when in doubt.
In case you prefer an alternative guide, weâve also prepared a demo video below. If your browser fails to load the video, head to this link to watch it.
Get your own copy of Espresso#
Open your browser and go to the Espresso repository.
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.
Now click the âForkâ button on the top right.
Leave everything by default and click the green âCreate forkâ button.
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.
We will clone your fork into your local machine. Click the green âCodeâ button first, and then copy the content under the âHTTPSâ tab.
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> cd espresso git remote add upstream https://github.com/inlab-geo/espresso git fetch upstream
Instructions for first-time GitHub users
If this is the first time you clone a GitHub repository, itâs very likely that you will need a personal access token as your password.
Option 1 - Check out this page: creating a personal access token for how to create a personal access token, and use it as your password when you are asked to enter it in the terminal.
Option 2 - Alternatively, set up SSH key and upload your public key to your GitHub account. Follow instructions in this page: Generating a new SSH key and adding it to the ssh-agent for how to set up SSH keys with GitHub.
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#
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.
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 .
Create a folder for your new contribution under
contrib/<problem-name>
, by running the following in your terminal:python <path-to-espresso>/espresso_machine/new_contribution/create_new_contrib.py <problem-name>
Replacing
path-to-espresso
with your path to the espresso folder youâve just cloned, andproblem-name
with your Espresso problem name, with lower case words connected by underscores (e.g.gravity_density
,polynomial_regression
).Navigate to folder
<path-to-espresso>/contrib/<problem-name>
, and youâll see template files.Read instructions in the
README.md
file, and you will know what to do next đ§đœâđ»đ©đ»âđ»đšâđ»You should already have all the âpre-requisitesâ installed if youâve gone through the steps above.
See a list of âChecklistsâ. These are pretty much all the things youâve got to do to complete this contribution.
When youâd like to perform a quick local test by running your own code, run
python espresso_machine/build_package/validate.py -c <problem-name>
When you think youâve finished the coding, run
python espresso_machine/build_package/build.py --validate
Submit your changes#
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>
ismain
by default.
See also
Check this cheatsheet for a good reference of using Git.
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.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.
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.
After your contribution is merged to the main branch, you can request another change with the same workflow anytime you want. Just keep your own fork, edit, commit and push to your own fork, and raise a pull request from there.
Thanks again, for your contribution to open source đ
Appendix I: installation steps#
To install your development version locally, run the following in your terminal:
$ python espresso_machine/build_package/build.py
The following table describes what happens when we package Espresso:
Step |
Whatâs done |
How itâs done |
---|---|---|
1 |
Clean |
|
2 |
Move meta data files to |
|
3 |
Move |
|
4 |
Move |
|
5 |
Write dynamic version and extra versioningit configs into |
|
6 |
Install package from |
|
Appendix II: validation steps#
To test whether your new contribution aligns with the Espresso standard, run the following in your terminal:
$ python espresso_machine/build_package/validate.py -c <contrib-name>
You can run the validation script before (--pre
flag on) and/or after (--post
flag on) you install your development version of Espresso. A better workflow is to run
both:
$ python espresso_machine/build_package/validate.py --pre -c <contrib-name>
$ python espresso_machine/build_package/build.py
$ python espresso_machine/build_package/validate.py --post -c <contrib-name>
Or the following for a complete check on all examples (including yours), both before and after Espresso installed:
$ python espresso_machine/build_package/build.py
Anyway, run the following for a detailed usage of this script:
$ python espresso_machine/build_package/validate.py --help
The following table describes what happens when we validate a certain version of Espresso:
Step |
Whatâs done |
How itâs done |
---|---|---|
1 |
Check the contribution folder name matches the main Python file name ( |
|
2 |
Check |
|
3 |
Check the class name is listed in |
|
4 |
Check the contribution provides access to the required metadata |
Pull out the |
5 |
Check required methods / properties are implemented and a complete workflow can run for each example number |
Run from |
6 |
Check optional methods / properties, if implemented, have the correct type signatures |
For each example, check that the outputs of |
7 |
Check |
|