Contribute

Introduction

The KiCad libraries are organized in repositories at the KiCad organization on GitLab. User contributions to these libraries are greatly appreciated, whether it is improving existing components or creating new ones.

How to contribute

To contribute to the KiCad libraries, submit a merge request on GitLab for the relevant repository.

If you are new to GitLab, please check out this guide Getting Started with GitLab before you start.

Making a Merge Request

The KiCad libraries are hosted on GitLab - users can submit their contributions using the Merge Request mechanism. Instructions for submitting a merge request are provided below.

  1. If you do not have one, create an account on GitLab

  2. Fork the repository you wish to contribute to

  3. Clone your newly created fork to your local machine

  4. Create a new branch in your local repository. This allows you to work on multiple contributions at the same time.

    1. Make sure the branch starts from the current HEAD of the master.

    2. Don’t add unrelated changes into the same branch

  5. Perform any necessary modifications to the library repository. Refer to the KLC for contribution guidelines.

  6. Commit your changes to the local repository, with a message describing the changes you have made. Complex changes may require multiple commits.

  7. Push your local changes to the GitLab remote.

  8. Create a merge request (MR) to merge your branch into the KiCad libraries. Include links to reference documents (e.g. datasheets) in the comments, in addition to a description of the changes you have made. Follow the instructions given in the MR template.

  9. A librarian will review the changes - discussion and further work may be required.

  10. Should further changes be required then push to the same branch as connected to the merge request.

    1. Small, individual commits are prefered since they are easy to review.

    2. Please do not alter the history of that branch once a review has started (no force-push).

    3. However, if there is a conflict preventing your changes from being merged into master a rebase or merge is accepted.

It is very helpful to the library team if you can include a description of your contribution and also a screenshot of your contributed file(s) (symbols / footprints / models).

Example:

adding_screenshot

KLC

When creating/editing/fixing a symbol or footprint a set of conventions should be followed. They are the KiCad Library Convention, or KLC for short. It is important the users are familiar with the KLC before making a contribution.

The KiCad librarian team have also developed a set of helper scripts written in Python which users can use to check their contributions against KLC guidelines before submitting.

Scripting Tools

EDA library elements can be highly repetitive, and can benefit greatly from scripting tools. In fact, many of the components in the KiCad libraries have been scripted using tools developed by the KiCad community.

Footprint Creation Scripts

kicad-footprint-generator is a very comprehensive footprint generation tool written in Python. The script toolset contains comprehensive examples and a large array of scripts used to generate many footprints that can be found in the KiCad libraries. Scripted footprints are easier to review for the librarian team since only the parameters need a review. Please always check if there is a generator suitable for your contribution.

Parameteric 3D Model Generation

kicad-packages3D-generator is a scripting toolset which allows 3D models to be generated parametrically using Python. It uses the CadQuery module from within FreeCAD (both of which are required to use the scripts). It is currently being ported to use strictly Python, CadQuery and pythonocc.

Become a librarian

If the 'merge request' world is too small for you, feel invited to join the librarians team. The easiest option is to simply start reviewing a few merge requests. Maybe tag the library leader to make them aware of your intention. Or open an issue on one of the library repos informing the team about your intentions. Alternatively send an e-mail to one of the librarians.

Currently KiCad librarians team counts with just a few people against a lot of merge requests and work to do, having your help would be very appreciated.

Contacting librarians

The best option is to create an issue on the GitLab repository that best fits your question. If you want to have a private conversation then send an e-mail to one of the existing librarians.

Many of the librarians can also be contacted on the KiCad user forums.