Set up GitHub

General workflow

        %%{init: {'theme':'base'}}%%
  flowchart LR
    subgraph PREPARATION [ preparation ]
      direction TB
      fork(fork repository)-->clone(create local clone)
      clone-->env_setup(environment setup)
    end
    subgraph EDIT [ editing ]
      direction TB
      code(start coding)-->commit(commit as needed)
      commit-->push(push to your own fork)
    end
    subgraph SUBMIT [ submission ]
      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
    

Setting up GitHub

We assume that any contributor has a Github account and established a secure connection using the GITHUB_TOKEN or SSH. If you wish to set up a new account or want to know how to set up a secure connection before contributing, please see here: Getting started with Github.

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.

Fork and clone

1. Navigate to the GitHub repository

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

   

   

3. Now you will be redirected to your own fork of Espresso, where you can freely commit changes and add your code.

   

           %%{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. Next, create a local copy of your fork of the Espresso repository using “clone” (the Github equivalent of download):

   

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

   replacing YOUR_GITHUB_ACCOUNT with your own account.

5. Open your local copy (folder espresso) using your favourite editor (VSCode, Spyder, etc.). Continue with setting up development environment.