+++
title = "Contribute"
summary = "The basics of contributing to KiCad libraries"
[menu.main]
    parent = "Libraries"
    name = "Contribute"
    identifier = "libraries_contribute"
    weight = 30
+++
:toc: macro
:toc-title:

toc::[]

== Introduction

The KiCad libraries are organized in repositories at the https://github.com/KiCad/[KiCad] organization on GitHub. 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 pull request on GitHub for
the relevant repository.

If you are new to GitHub, please check out this guide
https://guides.github.com/activities/contributing-to-open-source[Contributing to Open Source on GitHub]
before you start.

=== Making a Pull Request

The KiCad libraries are hosted on https://github.com/kicad[GitHub] - users can submit their contributions using the *Pull Request* mechanism. Instructions for submitting a pull request are provided below.

. If you do not have one, create an account on https://github.com/join[GitHub]
. link:https://help.github.com/articles/fork-a-repo[**Fork**] the repository you wish to contribute to
. link:https://help.github.com/articles/fetching-a-remote[**Clone**] your newly created fork to your local machine
. Create a new link:https://help.github.com/articles/github-glossary/#branch[**branch**] in your local repository. This allows you to work on multiple contributions at the same time.
.. Make sure the branch starts from the current HEAD of the master.
.. Don't add unrelated changes into the same branch
. Perform any necessary modifications to the library repository. Refer to the link:/libraries/klc[KLC] for contribution guidelines.
. link:https://help.github.com/articles/github-glossary/#commit[**Commit**] your changes to the local repository, with a message describing the changes you have made. Complex changes may require multiple commits.
. link:https://help.github.com/articles/github-glossary/#push[**Push**] your local changes to the GitHub remote.
. Create a link:https://help.github.com/articles/using-pull-requests[**pull request**] (PR) 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 PR template.
. A librarian will review the changes - discussion and further work may be required.
. Should further changes be required then push to the same branch as connected to the pull request.
.. Small, individual commits are prefered since they are easy to review.
.. Please do not alter the history of that branch once a review has started (no force-push).
.. 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:**

{{< klcimg src="adding_screenshot" title="Add a screenshot" >}}

== KLC

When creating/editing/fixing a symbol or footprint a set of conventions should be followed. They are the link:/libraries/klc/[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 link:https://github.com/kicad/kicad-library-utils[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

link:https://github.com/pointhi/kicad-footprint-generator[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

link:https://github.com/easyw/kicad-3d-models-in-freecad[kicad-3d-models-in-freecad] 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).

== Become a librarian

If the 'pull request' world is too small for you, feel invited to join the librarians
team. The easiest option is to simply start reviewing a few pull 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 pull requests and work to do, having your help would be very appreciated.

== Contacting librarians

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

You can also use the link:https://launchpad.net/~kicad-lib-committers[KiCad library mailing list] but be aware that it is not closely followed.

Many of the librarians can also be contacted on the link:https://forum.kicad.info/[KiCad user forums].
