New Espresso problem
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
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#
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 clonecommand 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>
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.
<path-to-espresso>/espressofolder 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.
Python >= 3.6 is required.
If you use mamba / conda, run
conda create -f envs/environment_contrib.ymlunder 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
EspressoProblemand 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>/tools/new_contribution/create_new_contrib.py <problem-name>
path-to-espressowith your path to the espresso folder you’ve just cloned, and
problem-namewith your Espresso problem name, with lower case words connected by underscores (e.g.
Navigate to folder
<path-to-espresso>/contrib/<problem-name>, and you’ll see template files.
Read instructions in the
README.mdfile, 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.
Check the boxes under “getting started”. 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, tips under “how to unit test your code” can be useful.
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#
It’s helpful to “commit” your changes when you have any progress. Feel free to make commits as often as necesary.
git add <file-name-1> <file-name-2>to choose which files you’d like to include in the following “commit”.
git commit -m "progress in xxx"to commit your changes.
git push origin <branch-name>to push your changes onto your GitHub fork, where
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>/espressoin 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.
Thanks again, for your contribution to open source 🌟