Skip to content

Taking part to a GlacioHack

Jump to bottom
Amaury Dehecq edited this page May 18, 2021 · 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. Create a fork of the repositories you plan to work on.

  2. Clone the repositories on your computer, e.g.:

cd path/where/to/install
username=your_github_username
git clone https://github.com/$username/GeoUtils.git
git clone https://github.com/$username/xdem.git
  1. Install the repository: this should be explained at each repository's level (here for GeoUtils and xdem) 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

N.B.: Installing the whole environment will take several minutes, be patient... or read the N.B below... and yet be patient as it may still take several minutes.
N.B.2: 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 master GitHub repositories to your remotes (only once):
cd GeoUtils
git remote add upstream https://github.com/GlacioHack/GeoUtils.git

# Check that it worked with
git remote -v

The last command should display something like: origin https://github.com/your_username/GeoUtils.git (fetch) origin https://github.com/your_username/GeoUtils.git (push) upstream https://github.com/GlacioHack/GeoUtils.git (fetch) upstream https://github.com/GlacioHack/GeoUtils.git (push)

Similarly for xdem:

cd ../xdem
git remote add upstream https://github.com/GlacioHack/xdem.git
  1. Fetch the latest version and merge into your master (example for GeoUtils)
cd GeoUtils
git checkout master
git fetch upstream master
git reset --hard upstream/master

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

  1. 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

  1. 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

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

  2. 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.

  1. 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.

  1. 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.

  1. 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 !!

  1. Delete your branch

When the PR is merged, please clean your branches, both locally and remotely:

git checkout master
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.

Clone this wiki locally