Skip to content

Taking part to a GlacioHack

Jump to bottom
Amaury Dehecq edited this page Apr 27, 2023 · 10 revisions

This wiki page summarizes tips on how to contribute to the GlacioHack packages during a hack event.

Install a local copy of a GlacioHack repository

  1. On GitHub, create a fork of the repositories you plan to work on.

Note for Windows users: The following commands work for a Unix environment, but they should also work if you install Anaconda and type the commands in the "Anaconda prompt".

  1. Clone the repositories on your computer, e.g.:
cd path/where/to/install
username=your_github_username  # or replace directly with your username below for Windows users
git clone git@github.com:$username/GeoUtils.git
git clone git@github.com:$username/xdem.git

Note: the commands provided are for connection with the ssh protocol. For this you may need to setup an ssh-key on GitHub. If you prefer to use HTTPS over SSH, you can replace all "git@github.com:" instances by "https://github.com/". More info on the different protocols can be found here.

  1. Install the repositories: this should be explained at each repository's level (here for GeoUtils and xdem). For development, I recommend installing the dependencies for xdem, which include all the dependencies for GeoUtils and more. This requires installing conda if not already done.
# Install xdem dependencies
conda env create -f ./xdem/environment.yml
conda activate xdem
# Install the dev dependencies, needed for testing etc
pip install -r xdem/dev-requirements.txt
# Install xdem
pip install -e xdem
# Install geoutils and force use the cloned version instead of pip's
pip uninstall geoutils
pip install -e GeoUtils

Note: Installing the whole environment will take several minutes, be patient... To speed up the process, you may want to use mamba instead of conda:

conda install -c conda-forge mamba
mamba env create -f environment.yml

and replace all other conda commands with mamba.

  1. Test that the install worked. The following command should return no error:

python -c "import geoutils; import xdem"

Get the latest version of GeoUtils/xdem - To do before making any change to the code

  1. Add the main GitHub repositories to your remotes (only once):
cd GeoUtils
git remote add upstream git@github.com:GlacioHack/GeoUtils.git

# Check that it worked with
git remote -v

The last command should display something like:

origin git@github.com:your_username/GeoUtils.git (fetch)
origin git@github.com:your_username/GeoUtils.git (push)
upstream git@github.com:GlacioHack/GeoUtils.git (fetch)
upstream git@github.com:GlacioHack/GeoUtils.git (push)

Similarly for xdem:

cd ../xdem
git remote add upstream git@github.com:GlacioHack/xdem.git
  1. Fetch the latest version and merge into your main (example for GeoUtils)
cd GeoUtils
git checkout main
git fetch upstream main
git rebase upstream/main

Alternatively to the third command, you can do git fetch --all --prune to update all branches and remove deleted ones.

To implement a new feature or fix a bug

  1. Create a new local branch - the branch name should state what the feature/fix is e.g. (feature/coreg or fix/bug1)
    git checkout -b branch_name

  2. Make changes to the code with your favorite editor.
    Try following the contributor's guidelines summarized here: https://github.com/GlacioHack/xdem/blob/main/CONTRIBUTING.md#code-conventions

  3. Commit your changes. Note that commits should be small incremental steps.

git add path/to/modified/file
git commit -m "A message summarizing the changes"

  1. Push your changes to a remote branch on your fork
    git push --set-upstream origin branch_name

  2. Iterate 2-4 to include as many changes as needed to fix/improve code.

  3. Test that your changes didn't break the existing code.
    From within the git repository folder, run pytest -v.
    If any error show up, try to understand if this is related to the change you've made. If in doubt, ask someone in the core developers team.

  4. Add a new test to ensure that the bug is fixed or the new features does what is expected.
    We use pytest for this. All tests are saved in the folder 'tests/', one file per module. For example in GeoUtils, 'tests/test_georaster.py' for all tests related to georaster.py.

  5. Create a pull request (PR).
    The simplest is to go to the GeoUtils/xdem GitHub page, click on the "Pull requests" tab (e.g. here for GeoUtils) and GitHub should suggest a PR.
    In the PR, you can add a reviewer and a label (bug, enhancement, documentation etc). At least one other person will need to review your code and validate your changes. This ensures the changes are in line with the structure and design of the projects and that functionalities are not broken.
    Additionally, the tests will be run in the background and if tests fail, it will not be possible to merge the PR. Tests typically take 5-10 min to run, so one need to wait after each new commit. You can also set your PR as 'Draft' to prevent the tests from running.

  6. Merge the PR.
    Once at least one person approved your changes and all tests succeeded, you can merge the PR using the button on the GitHub page. Your changes will be merged in the GlacioHack main branch and will be available to everyone !!

  7. Delete your branch.
    When the PR is merged, please clean your branches, both locally and remotely:

git checkout main
git branch -d branch_name   # delete your local branch
git push origin --delete branch_name    # Delete the remote branch

You can view all your branches with git branch -a. The ones with 'remotes' prefix are the remote ones, possibly including branches from other contributors (yours will start with remotes/origin) and the ones without the 'remote' suffix are the local ones. To ensure you see the updated branch list, type:

git remote update remote_name --prune
Clone this wiki locally