I have been using KiCad as a consultant for some time now, but I have recently moved to a new position where I will need to actively collaborate with more people.
I already use GitHub fairly effectively for tracking individual single-board projects and issuing releases; I do it manually right now as I have not automated this yet but would like to in the future.
My biggest question relates to library management. Ideally I would like to (privately) publish and maintain a set of libraries which themselves are version controlled. What would be ideal would be for a certain project to have a certain version of a certain library that it can just reference and whenever we decide to make a new iteration of that board, we can choose to update the library version that it is using. This should happen automatically when you clone the project, and not depend on what libraries happen to be installed on that machine. I would prefer for the footprint and symbol libraries to be global as they are reused often between projects.
I know that KiCad has a plugin and content manager that can deal with versioned libraries, but this only appears at the installation level? I guess you could mange this by having multiple version of the same library with repository showing the full history but this would get very messy.
I know Git submodules are also a thing and I have tried using them before but they seem to be more finicky than I would expect. Does anyone had a good expoerence with these in a KiCad context?
Any other suggestions or workflows to get this working would be apprecatied!
We put the library in its own git repository and share this folder(repository) thru windows share. Everyone with the write permission can edit the library and someone will commit the change from time to time. Each PCB project is also a git repository. It always refers the most current library. Using git subtree or submodule is not a good idea if you have a lot of PCBs.
I am not sure what the value of doing this is: since the link between a project and its libraries is “loose”, schematics/boards are not automatically updated when you change a library – you have to manually choose to update symbols or footprints from libraries.
Because of this, I don’t see the benefit in “versioning” the library itself: if you make a project, it will use whatever is the latest version of the library at that time, but then if you come back to that project a year later, it won’t automatically update the symbols and footprints to the new library versions (if they are changed in the library) – you have to explicitly choose to do that action. In a sense, the schematic/board files themselves already store the “version of the library” at the time that the design was made, for any symbols/footprints that are actually stored in the design.
I take your point but do you have a good colaborative workflow you can share for libraries? Really I just want a good way of synchronising libraries between memebers of a team at a project level. Ideally automatically.
It seems like a package manager (with a package being a footprint or component library) would be the ideal solution and somewhere within the project you can just choose which libraries you want to use and then to either always get the latest version, to stick with a particular version, or to prmpt whether you want to move to the newest version? Similar to how GitHub actions, Python, PlatformIO etc. manage dependicies.
I beleive KiCad’s current Plugin and Content Manager allows you choose a library to download, but you still have to install it yourself (and it’s not always clear where it has been installed)?
I use KiCad collaboratively within a company, as the title of your thread says. We do not synchronize libraries at a project level. We just have global shared libraries that are stored in version control (git).
There is no automatic workflow: users all have to choose when to pull and push from the git server, and when to update their projects’ symbols/footprints from library. This is desired: we don’t want changes one person pushed to automatically show up in someone else’s project without their knowledge.
Thanks for your responses, really appreciate the insight.
Would you say what you do is the current best practice in the industry? I only ask because it seems like a very different approach to the one I have used in collaborative software development where library versioning is explicit.
I have a few follow up questions if you don’t mind (and are able to share):
Do you have a single large repo containing multiple libraries? Or repo for each library? Or repo for each project library (but accessible globally)?
Do you store 3D models/ data sheets/ additional documentation in the repos?
Do you allow anyone to push changes back into the main branch, or do you require a Pull Request with some kind of review?
Do you have some kind of company standard (written or unwritten) on how the libraries should be named, structured, information to include etc?
Do you, as PCB designers, maintain the footprint libraries yourself in a distributed way with minimal oversight, or do you have a designated person who is responsbile for mainting the footprint libraries (that could include adding new footprints, or just approving and verifying pull requests)?
In my opinion there is not one single industry best practice. There are competing practices from various tools, proprietary and open source, and I don’t think one practice can be the right path for every team at every company.
If you are comparing to software development, keep in mind that because symbols and footprints are copied into schematics/boards, not just linked, it is more like “vendoring all your dependencies” in the software world: you don’t need to maintain Version A of a symbol library for Project A, and Version B for Project B. You just always make the symbol library better, and if some of that improvement involves changing existing symbols (rather than just adding new symbols), you decide if and when to backport those changes to Project A.
One large repo containing multiple libraries. Actually, a monorepo containing both libraries and projects in my case, but that part is not super important in my opinion.
3D models of components: yes, these are dependencies of footprints and must be stored alongside footprints. 3D models of finished PCAs: no, these are outputs (like gerber files) and we don’t store outputs in version control of the design data.
This depends a bit on team size, discipline, and other review processes. It can work to require review for every library change, but this generally warrants having multiple repositories (at least, not storing libraries in the same repo as designs) because in my experience you always want to let designers push directly to the repository when it comes to designs. Version control for hardware is a bit different from software in my experience in that there isn’t usually “continuous integration” in the fullest sense of the term; it’s not like a board automatically gets fabricated when you run “git push”. So, in general it makes more sense to encourage many commits, to get plenty of history and backups of the designer’s work, and then do a more formal design review before fabricating boards based on outputs.
For libraries, you can also do this style, and then review any changed footprints as part of the board design review process, or you can do more like the KiCad public libraries, and have a pull request workflow for any library change. I think it’s a matter of preference where you insert review of symbols/footprints in your process, as long as it exists somewhere.
Yes. Much like the KLC dictates this for the public KiCad libraries, we have internal standards and best practices to check off during a review. For example, we ask people to follow IPC naming convention for footprints.
My current team distributes this responsibility among all the designers. I’ve been on other teams that centralize this role. I think it depends on the “style” of the company, how big it is, whether or not it would make sense in that company culture to have a dedicated “librarian” or not.
we have three repos for main libraries (symbols, footprints, 3D models)
the libraries are based upon KiCad’s official library with a couple of additional libraries. This makes if possible so that members can contribute back to the KiCad library. And as they are a private fork we can use the manufacturers 3D models without licensing issues as we are not redistributing 3D models
once the project is complete it is archived along with 3D models (using an Archive3Dmodels plugin)
any new symbols/footprints are put in the project wide libraries. Once we have the design tested, the symbols/footprints are merged to the main library. And the merge process is a two person job (one requesting merge and one verifying and confirming it)
We try to conform to KLC for new assets
we don’t have any access control/branch protection in place for write access to main libraries
as we are a small department we don’t have a dedicated librarian. And even in bigger companies this might not be a smart organizational approach as they tend to become a choke point.
The only issues with pulling upstream changes are:
lib table files (sym-lib-table and fp-lib-table) as we add our library entries and we disable libraries whic we don’t use (valve, …). These modifications enable quick start to new users as they get “proper” library tables along with the libraries. Pulling upstream changes for these files is not problematic as they change rarely.
symbol library files (*.kicad_sym) change more often and there are three approaches:
you don’t put any symbol into KiCad libraries. So you have no conflicts on pulling upstream changes, but then you have symbols which fit one category in different libraries (e.g. KiCad’s DC/DC converter library and your own library where you keep symbols for DC/DC converters)
you can upstream all the symbols that you put in KiCad’s libraries. This requires some patience as library maintainers are overstretched and you might wait. And you will still get some conflict when pulling from upstream (different symbol added to upstream than what you’ve added locally)
the middle path. Put some symbols in the KiCad’s library, upstreaming just a portion of these and handling conflicts when pulling from upstram
In any case conflict resolution in the symbol library files is usually quite easy as it most commonly requires just to insert new symbol before/or after yours. The most difficult conflict resolutions are the ones where a symbol for the same component, that you already have has been added but it is slightly different. Syntactically this is not an issue, but you need to decide within the department what to use from now on forward. So it becomes a process issue. We mark our symbol as deprecated and try to use KiCad’s version of it.
Also having your “release” version of the library on a different branch helps a lot. Then you can pull upstream locally and pull into the “release” branch when you are prepared.
Less repos is generally easier unless there is a really good reason to have multiple.
With tools like Github/Gitlab/Gitea, you can protect the main branch and require review before merging to main, etc.
We’ve not done this yet, but are exploring using a database for parts lib and would like to avoid requiring a network connection to a DB. So one idea we had was to store the parts lib in a CSV file and then have a tool that unpacks that into a SQLite database, and then use that in KiCad. Then the CSV file could be easily stored and review in Git. BTW, Gitea does an excellent job of diffing CSV files – see example below:
