As of a month ago (May 20th), I’m officially a KiCAD Librarian. One of my first things I did was merge a bad YAML, then break CI for myself… Erm…

Luckily, no one was injured (probably because I’m not in wrench-throwing distance to the other Librarians — okay, in all seriousness they were pretty chill about it, and all around nice people), and we fixed everything up pretty quickly. But it was an exciting hour for me for sure…

Anyhow, to offset this, and because I’m passionate about KiCAD (which is why I joined), the next day I decided to make a contribution guide for my colleagues at work. For your viewing pleasure, here is the English version. Contributing to a well-known Open Source project can seem dreading at first, and although KiCAD’s contribution pipeline is pretty easy (especially when compared to things like the Linux kernel, Git, Busybox etc.), there are a few nice-to-know things.

In this how-to, I assume that the reader is already familiar with Git itself, GitLab, Open Source, and KiCAD’s symbol and/or footprint editor. For the generators, you’ll also need to know a little bit of Python and YAML.

Contributing to the KiCAD Library

The KiCAD Library is available on GitLab

Project overview

The KiCAD project consists of 6 main components:

• the C++ code for the apps (this is all the non-library stuff, and thus outside the scope of this howto),
• the parts symbol catalogue (kicad-symbols),
• the footprint library (kicad-footprints),
• the 3D models (packages3d),
• the generators that create many footprints and most 3D models (kicad-footprint-generators),
• and other Python scripts responsible for QA checks, generation of some symbols etc. (kicad-library-utils).

General rules

Most of the rules you can find in the KiCAD Library Conventions (KLC). Maintainers (called Librarians here) use a simple checklist, the output of CI, and their individual insights to evaluate contributions. Being familiar with these documents and scripts will help you make a successful contribution.

Contributions must be made with the latest stable KiCAD version. In practice it is sufficient to have the major.minor (e.g. 9.0) version match the newest. You can use the KiCAD Flatpak from FlatHub, which updates regularly, unlike apt. Of course if you are brave enough, you could install kicad-nightly, and deal with the consequences… One more thing to keep in mind is that the newer KiCAD can read files made by older versions, so editing with the version you regularly use, then opening that in the newest KiCAD to add them to the library is a viable option (this will be explored in the next chapter).

The “source of truth” is the linked datasheet, in terms of naming, dimensions, values, it should be followed. Unless in the not-so-rare case, when it is nonsensical, or even full of factual errors, in which case you can deviate from it, provided you give a strong enough argument.

If you are contributing for the first time, make sure you read the template that shows up when you open the MR.

Development, automatic tests

To run the checker or the generator scripts, it is recommended to set up a Python Docker container as such:

# Clone everything to a common work dir
for p in symbols footprints footprint-generators library-utils
do
	git clone https://gitlab.com/kicad/libraries/kicad-${p}.git
done
# Enter Docker
podman run -it --rm -v .:/work python:3.12 /bin/bash
 
# In Docker
#  For FP or 3D generation
cd /work/kicad-footprint-generators
pip install -e '.[dev]'
#  For everything else
cd /work/kicad-library-utils
pip install -r requirements.txt

In order to be able to edit the libraries cloned with Git, you need to add them to KiCAD. This is best achieved by creating an empty dummy project, then from the project manager window, go to Preferences -> Manage <Footprint/Symbol> Libraries -> Project Specific Libraries, then click the little plus button and add the .kicad_mod or .pretty paths, with a distinguishable name (such as Resistor_SMD-master). Important to note, however, is that if you’re adding a new symbol and want to reference a footprint that only exists in Git, then you have to add that footprint library with the original name (e.g. Package_BGA)! This hides the built-in catalogue, but will add the correct footprint name to the symbol.

Automatic checkers

Scripts for checking adherence to KLC rules: /work/kicad-library-utils/klc-check/check_*.py. It is recommended to run these before submitting the MR, but the CI will run it anyways and report errors. Keep in mind that this is a simple checker, and does not handle everything.

Tips for a successful contribution

Some KLC paragraphs leave room for a more subjective interpretation, and Librarians can also give us some leeway, if given a strong enough argument by the contributor. More on these below.

All Merge Requests can benefit from having screenshots attached, this can be done by selecting File -> Export -> View as PNG in the (footprint or symbol) editor, or File -> Export current view as PNG in the case of the 3D viewer (accessible by pressing Alt + 3 in the footprint editor). It is also recommended to link the datasheet PDF in the MR as well, and optionally screenshot the relevant parts too.

All library items must have an associated datasheet! In the case of footprint MRs, it is recommended to check if the manufacturer has a separate datasheet just for the package (there usually is). This is important so that the reviewer does not have to flip through 300 pages of MCU docs just to see the package dimensions, and also because manufacturers usually version control (and thus may change) them separately.

The golden Git rule of keeping the diffs minimal (don’t reformat the entire file for example) also applies here.

Special rules for symbols

Maybe the most subjective paragraph of KLC is S4.2 Pins should be grouped by function. The automatic checker only checks that all pins are arranged on the correct side (power on top, ground bottom, inputs to the left, outputs to the right etc.) of the part, the rest is up to the reviewer to check. Here you have to use your common sense (if you have it; if not, then borrow from someone), for example, pins that are part of the same interface (UART Rx/Tx, I2C SDA/SCL stb.) should be adjacent, interfaces that are loosely coupled to each other (such as Ethernet RGMII & MDIO) should be close to each other etc. In many cases, the order of the pins matter as well, so it is recommended to check for similar parts already in the library (e.g. when the part has a QSPI interface, refer to existing QSPI Flash symbols for pin ordering). And if you’re dealing with multifunction pins, then it’s totally up to you and the reviewer to reach a solution that makes sense.