Making changes to MapServer¶
Minor changes to MapServer, such as bug fixes, may be made by opening a GitHub pull request.
Major changes should be discussed on the mapserver-dev listserv and may require the drafting of a RFC (request for comment) document.
This section collects a few best practices for git usage for MapServer development.
Initiating your work repository¶
Fork mapserver/mapserver from the GitHub UI, and then run:
git clone https://github.com/mapserver/mapserver cd mapserver git remote add my_user_name email@example.com:my_user_name/mapserver.git
Working with a feature branch¶
git checkout main # potentially update your local main 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 main if you need some bugfix # or new capability that has been added since you created your branch git fetch origin git rebase origin/main # At end of your work, make sure history is reasonable by folding non # significant commits into a consistent set git rebase -i main # 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/main git reset --soft origin/main 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 main, in which case you will have to force-push your
git push -f my_user_name my_new_feature_branch.
Updating your local main against upstream main¶
git checkout main git fetch origin # Be careful: this will lose all local changes you might have done now git reset --hard origin/main
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...
MapServer 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:
python3 -m pip install pre-commit pre-commit install
Once installed, the hooks can be run manually via
pre-commit run --all-files.
Blame ignore file¶
Due to whole-tree code reformatting done during MapServer 8.2 development,
git blame information might be misleading. To avoid that, you need
to modify your git configuration as following to ignore the revision of
the whole-tree reformatting:
git config blame.ignoreRevsFile .git-blame-ignore-revs