Development practices

Making changes to GDAL

Minor changes to GDAL, such as bug fixes, may be made by opening a GitHub pull request.

Major changes should be discussed on the gdal-dev listserv and may require the drafting of a RFC (request for comment) document.

GDAL’s policy on substantial code additions is documented at RFC 85: Policy regarding substantial code additions.

Git usage

This section collects a few best practices for git usage for GDAL development.

Initiating your work repository

Fork OSGeo/gdal from the GitHub UI, and then run:

git clone https://github.com/DSGeo/gdal
cd gdal
git remote add my_user_name git@github.com:my_user_name/gdal.git

Working with a feature branch

git checkout master
# potentially update your local master against upstream, as described above
git checkout -b my_new_feature_branch

# do work. For example:
git add my_new_file
git add my_modifid_message
git rm old_file
git commit -a

# you may need to resynchronize against master if you need some bugfix
# or new capability that has been added since you created your branch
git fetch origin
git rebase origin/master

# At end of your work, make sure history is reasonable by folding non
# significant commits into a consistent set
git rebase -i master
# use 'fixup' for example to merge several commits together,
# and 'reword' to modify commit messages

# or alternatively, in case there is a big number of commits and marking
# all them as 'fixup' is tedious
git fetch origin
git rebase origin/master
git reset --soft origin/master
git commit -a -m "Put here the synthetic commit message"

# push your branch
git push my_user_name my_new_feature_branch

From the GitHub UI, issue a pull request.

If the pull request discussion or automated checks require changes, commit locally and push. To get a reasonable history, you may need to combine commits using git rebase -i master, in which case you will have to force-push your branch with git push -f my_user_name my_new_feature_branch.

Updating your local master against upstream master

git checkout master
git fetch origin

# Be careful: this will lose all local changes you might have done now
git reset --hard origin/master

Commit messages

Commit messages should indicate a component name (eg a driver name), a short description, and when relevant, a reference to a issue (with ‘fixes #’ if it actually fixes it)

COMPONENT_NAME: fix bla bla (fixes #1234)

Details here...

Commit hooks

GDAL provides pre-commit hooks to run code linters before a commit is made. The hooks are cloned with the repository and can be installed using pre-commit:

python -m pip install pre-commit
pre-commit install

Once installed, the hooks can be run manually via pre-commit run --all-files.

Backporting bugfixes from master to a stable branch

git checkout master
With git log, identify the sha1sum of the commit you want to backport
git checkout 2.2 # if you want to backport to 2.2
git pull origin 2.2
# git checkout -b branch_name  # if you intend to submit the backport as a pull request
git cherry-pick the_sha1_sum
git push ...

If changes are needed, do them and git commit -a --amend

Things you should NOT do

(For anyone with push rights to OSGeo/gdal) Never modify a commit or the history of anything that has been committed to https://github.com/OSGeo/gdal

Committing symbolic links is allowed only under the .github directory in order to avoid potential problems on Windows.