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.
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 firstname.lastname@example.org: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
git rebase -i master, in which case you will have to force-push your
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 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...
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
Committing symbolic links is allowed only under the .github directory in order to avoid potential problems on Windows.