git clone https://git.launchpad.net/kicad
KiCad uses Launchpad for bug reporting and tracking, source code hosting, and creating blueprints (roadmaps) of new features. The project is essentially managed through Launchpad. The first thing to do before anything is to join the KiCad Developers Mailing List. You can also join the IRC channel if you have questions. Usually, there are multiple KiCad developers in the channel.
To report bugs and help with technical subjects you will need a Launchpad account. To commit source code, you will additionally need to set up SSH keys for your account. Detailed instructions for setting up an account are available in the Launchpad user tutorial.
The official road map is available online as the version 5 road map in the doxygen docs. The CERN team also have their own road map available at CERN KiCad work packages. You might use this to get a feeling of where KiCad is moving and where you can contribute.
The first step is to obtain the source code. You will need to get the latest sources in order to develop KiCad.
KiCad uses the git version control
system. Platform-specific installation instructions are available
here. On Debian and related
systems (e.g. Ubuntu), you need to install the
git package. On
Windows, you’ll need to download and execute the installer.
Once you have git installed, you just need to clone the official repository, like so:
git clone https://git.launchpad.net/kicad
You can pull the latest changes in your clone with:
Follow the instruction in the documentation corresponding to your platform to set up a working build environment and successfully build KiCad from source.
After you have setup your development machine by fetching the source and making sure that you can build as described above, you might or might not know what to actually contribute. If the latter, this is the page for you.
The next thing to do is to check out the KiCad Coding Style Policy - it’s important for us to keep the codebase readable by all developers. This generally gets philosophical, but the code base needs consistency throughout, so please do pay attention to the code style policy. Your patches will generally be rejected if they do not adhere to the rules set forth in the policy.
If you feel like working on the user interface, you may find useful reading the User Interface Guidelines.
Do not feel discouraged, though, if your first patches don’t make it first go due to policy violations you can take it as a pretty high compliment.
To familiarize yourself with the code base you can read the
documentation generated by Doxygen. When submitting new code, please
remember to update the documentation descriptions. You can run
make doxygen-docs to generate the documentation locally.
The latest version of the same docs are also available on the Jenkins server, see KiCad Developer Docs for the C++ API.
If you are new to KiCad development you might want to look into bugs tagged as 'starter'.
Or for example if you are an OS X user, you might want to check the following bugs tagged as 'osx'.
git is a distributed version control system, which, unlike centralized systems like SVN, allows you to commit and manage your changes in your individual clone or "fork" as it’s known in GitHub.
Once you’ve made some changes to the codebase that you think on submitting to the project, you should commit them onto your clone.
But first, you need to set up your name and email on git if you haven’t already. This will ensure that you get proper credit for your contributions.
git config --global user.name "YOUR NAME" git config --global user.email "YOUR EMAIL ADDRESS"
That out of the way, commit your changes like this:
git add file-that-i-changed.cpp other-file.h etc git commit
Doing a git commit on it’s own will not do anything until you add the
changes that you mean to commit first, there is a good reason for
that, sometimes you’ve got some minor changes that are picked up by
the system but you don’t mean to commit, adding exactly the files you
mean helps you keep control of that. Please refrain of doing
git commit -a or
git add . unless you know exactly what you changed.
It is also useful to run
git diff --cached to see what’s staged for
commit before commiting, if you added files you didn’t mean to you can
remove them from the staging area by running
git reset bad-file.cpp
If you realized a mistake right after you commited, be it in a file
change, or you forgot a file, or the description has an error or a
typo, as long as you haven’t pushed your changes yet you can make your
changes and then run
git commit --amend, this will show you the
commit log from the last commit, let you edit it and will replace the
old commit with the fixed one.
Patches meant to fix a bug reported on the bug tracker need to be marked as such. Currently it is done by appending the following formula to a commit message:
Fixes: lp:12345678 * https://bugs.launchpad.net/kicad/+bug/12345678
To simplify the process, one can configure git to include an extra alias which marks commits as bug fixes. To enable it, run in the KiCad source directory:
git config --add include.path "$(pwd)/helpers/git/fixes_alias"
Afterwards you may mark commits using 'git fixes' command:
git commit -a -m "Fixed a memleak" git fixes 12345678
It will often happen that someone else with push access to the
official KiCad repository will push changes in between the time you
commited your changes and you decide to push/submit yours for
consideration. In that case if you try to run
git pull, by default
git will generate a merge commit, which is undesirable fluff and tends
to pollute the commit history. In those cases you want to run
git pull --rebase instead. What that operation does is to take your
commits and graft them on top of the master branch, which will allow
you yo push your changes cleanly, or submit a patch set that applies
cleanly on master.
You can make that behavior the default by running these commands:
git config pull.rebase true
Or to do it in all your projects and not just KiCad,
git config --global pull.rebase true
Patches are currently submitted and handled via the developer mailing list, where you have to apply for membership to be able to send to it. Alternatively, you can attach patches to bug reports or submit a merge request on Launchpad.
The easiest way to create patches from git is to first ensure that
your changes are rebased on origin/master (as they would be if you
git pull --rebase) and then use the
git format-patch --attach origin/master
That will generate a .patch file for each commit, which you can then attach to an email and send it to the developer’s mailing list, or you can use git-send-email to send them from git automatically.
If you plan on working on a more involved feature that will need many commits before it’s ready to be merged to the master branch you are encouraged to create your own branch. It is very easy to do in git.
First you need to check out your new branch:
git checkout -b new-hot-feature
Then just commit on it on every phase of your work. During that time the branch will diverge, that is, get out of sync with master. You have two choices on how to proceed, you can merge like this:
git fetch git merge origin/master
Which will create a merge commit, or you can rebase your branch onto master
git fetch git rebase master
Either way is fine as long as your repository is private, if you published your branch somewhere you should only use merges, as rebasing your branch will confuse whoever pulled your branch before.
You can publish your branch for others to pull and test by creating your own launchpad repository or uploading it to a git hosting site like GitHub.
If you wish to contribute eeschema, pcbnew or 3dviewer libraries, please see the Librarians page.
Feel free to join the IRC channel at #kicad@freenode. A nice bunch of people are casually hanging around in there, so if you have any questions and don’t know where to ask, you should try asking in here. There are all kinds of people in all kinds of time zones, both people who develop KiCad and plain enthusiastic users.