|Did you know ...||Search Documentation:|
|How to submit patches?|
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.
As of May 1, 2014, the primary repository of SWI-Prolog is at GitHub.
GitHub has a good description of submitting patches using pull requests.
Note that quite a few of the remarks below also apply to using GitHub, notably those about dealing with packages that are represented as git submodules.
You cannot fork on GitHub and next clone. If you try to do so, all submodules are resolved against your GitHub account and thus you must clone all repositories from the SWI-Prolog organization. Much better is to clone and then fork:
git clone https://github.com/SWI-Prolog/swipl-devel.git git submodule update --init
Now you have a complete working source tree you can compile and modify. If you want to create a pull request against one of the git repos, now fork it on github if you did not already do so, go to the top directory of the repo on your machine and run (you can also use
git remote add myfork email@example.com:me/repo.git
Now, after creating a topic branch, push it to github using
git push myfork mytopic:mytopic
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.
% git config --global user.name "The Great Fixer" % git config --global user.email firstname.lastname@example.org
% git checkout -b fixes
% 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
% git format-patch master
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 % git submodule update
Now, there are some options that may apply.
% git branch -D fixes
% git checkout fixes % git rebase master
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
% git commit -a --amend
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:
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.
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.