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.gitWe 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.gitSetup 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:
- Create a new (local) branch
- Commit our changes to that branch and write a good commit message
- 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)