This page describes how to submit patches if you find a bug or missing functionality. There are several options, which are described in decreasing preference.
Submit as GIT patch-sets (preferred)
Download the system as described in Accessing SWI-Prolog source via GIT. First we describe patches to the core system. Patches to packages that are distributed as git submodules are described below.
- Make sure git knows who you are. You only need to do this once
for your machine.
% git config --global user.name "The Great Fixer" % git config --global user.email email@example.com
- Switch to a branch. This makes it easy to distinguish between the
central version and yours.
% git checkout -b fixes
- Edit your files, making the necessary changes. Test your changes.
Make sure you changed nothing unwanted using
% git diff
If you are happy, commit them using the command below. Please add a sensible story that explains what has been added, fixed, .... If you want the change to appear in the release notes, make the comment start with a word in capitals, followed by a colon (:). Typically, this is
PORT:. The set is not fixed, but try to reuse old keywords.
% git commit -a
- Create a patch-set. The command below creates a file for each commit
between the master branch and your fixes branch. It creates files 0001-*,
0002-*, etc. Send these files to firstname.lastname@example.org, one file per
mail. The commit comment is part of these files, which should be enough
to explain what you did why.
% git format-patch master
How about submitting patches to a package?
This is slightly more complicated because packages are git submodules and submodules are `not on a branch'. Therefore, you need some more preparation. Go to the directory holding the package you want to patch. Then use these commands to turn this into a normal repository. After that you can follow the same steps as above.
% git checkout master % git pull
At some point you may want to synchronize with the upstream version. You do this by switching branches, and update as usual:
% git checkout master % git pull % ./prepare
Now, there are some options that may apply.
- All changes were accepted
Simply discard your fixes branch using
% git branch -D fixes
- No changes are applied upstream (yet)
Go to your fixes branch and rebase it:
% git checkout fixes % git rebase master
- Some changes were accepted, others not and you want to keep using them
Move your branch, recreate it and selectively pick the commits you want
to keep. You can find the hashes of the commits using
git log. The sequence is:
% git branch -m fixes tmp % git checkout -b fixes % git cherry-pick <hash1> % git cherry-pick <hash2> % ... % git branch -D tmp
Do's and Don'ts
- Use small commits
- Do not put multiple changes into the same commit. The ideal commit establishes exactly one fix or addition.
- Amend commits
Often, you'll find that the commit you just created is wrong or
incomplete. As long as your commit is only known locally, use
the command below to fix the last commit rather than creating
% git commit -a --amend
As simple git patches (2nd option)
Just checkout the version using git and use the command below to create a patch file.
% git diff > my-patches
This is less ideal because:
- There is no author in the GIT log. It can be very useful to know who did what when and you claim your work.
- There is no comment. Please add a comment to the mail about why and what.
As classical patches (3rd option)
You can also keep a copy and use the diff command to produce a classical
patch file as below. diff should be available on virtually any Unix system
and there are many ports for Windows. Use the unified (
-u) style to
% cp somefile somefile.orig <edit, test, etc> % diff -u somefile.orig somefile > my-patches
This is worse than using
git diff because git diff includes information
on the exact version that is patched, which can help us if there are other
conflicting patches. In addition to comments on the why and what, please
indicate the version you patched.
Send complete new files (please don't)
Please do not send complete files. They are hard to integrate. If you really must, at least accompany them with a clear description of what you changed and which version of the file you changed. Change as little as possible.