Developers

Getting Started

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.

Fetching the Source Code

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:

git pull

Build it!

Follow the instruction in the documentation corresponding to your platform to set up a working build environment and successfully build KiCad from source.

How to Contribute

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.

There are multiple ways of contributing to the future success of KiCad, one could contribute on the documentation, libraries or actual code contributions to the codebase.

Read the Code Style Policy

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.

Doxygen Documentation

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.

You can also find various developer notes in the Doxygen docs, see the related pages.

Starter Patches

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'.

Commit your changes

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.

Bug fixes

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

Pulling changes and rebasing

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

Submitting Patches

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 use git pull --rebase) and then use the git-format-patch command, like so:

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.

Managing your own branch

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.

Learn more git

This is a very light introduction to git, it is highly suggested that you read the excellent git documentation, and/or follow the many tutorials available online like this one.

In addition there are also some more tips on making commits in the developer docs.

Translating GUI and Docs

If you are the kind of person wanting to help improve KiCad by internationalizing it, you should probably have a look at the GUI translating howto.
Also you are encouraged to contribute to the KiCad Documentation

Contribute to the Official Libraries

If you wish to contribute eeschema, pcbnew or 3dviewer libraries, please see the Librarians page.

Internet Relay Chat (IRC)

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.