Contributing to the Kicad-library using gitlab and git

For some people it is rather easy to fix bugs in symbols, or create some new footprints. But the actual contributing step requires some working knowledge of git. As always with git, there are lots of different ways to reach the same goal. I will write down my preferred way, together with some explanations on why and how we do this. This post will only cover schematic symbols since the workflow for footprints or 3D-Models is identical.

Not everything is covered in this blog post, for example, the generation of a gitlab user account and its setup are out of scope. Here are a few resource to read up:

Get the library

On a typical kicad install, there are also symbol- and footprint-libraries installed. On a linux system they are read-only, so we can’t edit them. On windows we can change the files, but they might not be up to date with the latest version on gitlab (where all library development takes place). So what we want to do is clone the official repository and work with those symbols.

cd /home/cpresser/Documents/KiCad/
git clone git@gitlab.com:kicad/libraries/kicad-symbols.git

We also need to setup a fork of the symbols-library on gitlab where we can publish our changes. This can be done on the gitlab webpage by pressing the ‘fork’ button in the top right on the project page (https://gitlab.com/kicad/libraries/kicad-symbols/). Next we need to add this repository as a second remote to our local git repository.

git remote add cpresser git@gitlab.com:cpresser/kicad-symbols.git

Setup Kicad to use the git library

Next we want that Kicad also uses the library we just cloned. Depending on the operating system you are using, or even the package, there might be differences. On my system, I had to do two things.

1. Set the path to the library in Kicad, go to Preferences->Paths

2. Use the sym-lib-table from git. It resides in the config folder. So on my system I did the following:

cd /home/cpresser/.config/kicad/6.0
mv sym-lib-table sym-lib-table.old
ln -s /home/cpresser/Documents/KiCad/kicad-symbols/sym-lib-table .

3. Verify that its working. Open Kicad, go to the symbol editor and make some change, e.g. add a text to the default capacitor symbol in the Device library. After that, type git status and it should look something like this.

Since that was a useless change, just as a test, undo it with git restore Device.kicad_sym. Now you are set up do do library work. Yay!

Adding a symbol and opening a MR

Now the setup is complete, we can do some actual work. Lets assume we want to add a new symbol for a Lattice FPGA. In this case, just head over to the library editor inside Kicad and create a new symbol. When done, head back to the command line and type git diff so see if there are the changes you expect:

This looks good, there is exactly one hunk (= a group of changed lines) that correspond to the symbol we created in the editor. To upstream this, we need to do a few steps:

  1. Create a new (local) branch
  2. Commit our changes to that branch and write a good commit message
  3. Push that branch to our own fork on gitlab
git checkout -b Add_fake_Lattice_FPGA
git add -p
git commit
git push cpresser Add_fake_Lattice_FPGA

4. Create a merge request, just use the provided link

Make sure to fill out the merge request template to the best of you knowledge. And please don’t uncheck the “Allow commits from members who can merge to the target branch” checkbox. It make take some time until a librarian makes a review of you contribution, we are only volunteers and short staffed.

You can repeat this process for every contribution. Make a new branch with a descriptive name for each one. You can switch around different branches using the git branch <branchname> command.

Once your contribution gets accepted it will get merged into the master branch. You can then safely delete your local branch with git branch -D <branchname>.

Adding changes

In quite a few cases, the library maintainers will require you to do some changes during the review. As a first step, you need to switch back to your local branch that corresponds to the MR. Next do the changes in the Kicad symbol editor, then head back to the command line to create a commit and push it. Your merge request will automatically get updated.

git checkout Add_fake_Lattice_FPGA
# <now do changes in kicad symbol editor>
git add -p #(stage the changes for a commit)
git commit #(create a commit)
git push #(push that commit to the remote)

Checking KiCad symbols

In summer 2019 I have been invited to join the KiCad librarians team. As a librarian my job is to review additions and enhancements of the KiCad-library. Those include footprints and symbols in their respective repository.

All submissions should adhere to the KiCad Library Convention (KLC) which is a set of guidelines to follow when contributing to the library.

Unfortunately there is no on-boarding for new maintainers. And no ‘real’ process for checking contributions. It is up to the reviewer to learn all of that themselves. Thus, I decided to write down a small list of the items I usually check when looking at submission. This list is not comprehensive, so only take it as a starting point!

  1. Could the new symbol be an alias to an existing one
    • If its an alias, some of the checks can be skipped since the base part is already in the library. Only the dcm file which contains the keywords and description need detailed checking.
    • A quick check for the base part should be done anyway. This is a great opportunity to find bugs. If possible also fix cosmetic issues if it does not break compatibility.
  2. Are there symbols with similar function already in the library? If yes, does the new symbol conform to the style set by the existing ones?
    • Sometimes the existing style does not conform to KLC. Then some research should be done to figure out why that is the case. Some symbols are rather old and were made without proper checks
    • Perhaps the existing symbols needs rework as well. If its just a small amount of work and a non breaking change the contributor can be asked to take care of that as well.
  3. Is the new submission in the correct library section? There are some corner cases or even devices that by no means fit into an existing library. Then a new library can be started.
  4. Is the new symbol a generic or a fully specified symbol
    • Should there be additional aliases? For example fixed voltage regulators usually come in with different voltage options. It is good to have one alias for each output voltage.
  5. Check the Symbol name
  6. Pins
    • Verify names and pin-numbering against the datasheet
    • Are the pin electrical types helpful for the DRC? Most datasheets give information about pin types. Look for open-collector pins, special power pins, …
    • In most cases the GND pins can be stacked. Sometimes this also applies to power pins or even I/O.
    • If the package has an exposed pad or other features (shield, mechanical mounting), is that properly represented in the symbol
    • NC pins should be on the outline of the symbol body.
  7. Pin layout (which pins go on which side of the symbol)
    • Again, check for consistency with similar symbols
    • Perhaps ask the contributor to provide an example how the symbol would be used in a schematic.
    • Perhaps reshuffle pins (a popular example are XIN and XOUT for a crystal. Its useful to space them by 200mil so Crystal_Small fits between the pins)
    • Correct ordering (e.g. numbered GPIOs)
    • For multiple units: does the split make sense?
  8. Metadata
    • Matches the Datasheet, is consistent with other parts in the lib
    • Package name at the end of description for standard packages
    • Keywords exist and make sense, perhaps additional keywords required
    • Datasheet link exists, page-number anchor if applicable
  9. Footprint
    • Exactly matches datasheet (check drawing)
    • Datasheet matches kicad-footprint pin numbering (there are vendors that don’t follow JEDEC)
    • Filter matches, pin-count not included (unless required)

Perhaps I will make a similar list for footprints in the future.