How do KiCad development branches work?

I have recently filed a bug report on GitLab.

I can understand that we have multiple developers working on different bugs and development areas. I can imagine that considerable coordination is required to prevent the different developer’s work from “stepping on each other”. And once the individual developers have fixed various bugs, I think it would then necessary to combine them into a version which probably gets some preliminary testing prior to release as a development build. And then a lot more testing and refinement is needed before posting as a stable release version. And maybe I am all wrong…??

Anyway I would like to get a better understanding of the explanation in the bug discussion. What is a “commit”? I can guess but I am not sure…

A term of version control systems like git. A commit is the smallest trackable unit of changes inside git. A commit represents a snapshot of the code at some specific instance (the instance determined by when the developer creates the commit)

This is what the master branch is for. Fixes are now handled in merge requests (gitlab equivalent to githubs pull request). A merge request is as you noticed a separate branch. In it a number of commits are collected that address a certain issue. (a branch is generally just a pointer to some commit that represents the tip of that branch)

The merge request is then reviewed by one of the developers. If it is deemed ok then the changeset is merged into the master branch. This master branch is what is compiled into nightly builds.


For stable releases this is a bit more involved. At the end of the development cycle a new branch is split from master that will be used to handle bugfixes to that stable version. (Currently this is the 5.1 branch)
Fixes are then cherry-picked into the stable release branch (another git term that basically means “I would like to have the changes of that commit duplicated on my current branch”).
Or if master and stable have deviated too much then a separate fix needs to be developed for both of them (if the problem needs to be fixed in both the development and stable version)


Atlassian (the guys behind bitbucket, jira, …) have quite good tutorials. The general workflow of KiCad development can be seen as the gitflow workflow: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow (every merge request is a feature branch)

There is a nice childrens playground where you can play “code developer” and practice your commits without any danger:


Beside commit you should understand the clone, merge and rebase commands. Git is an invention of Linus Torvalds and not really easy to understand all details for non gits without to practice them. Also my first trial in contributing for i18n flew in under the radar and needed to be reverted. Finally @nickoe managed the pull request. Pull request was from last years Github and seems now replaced by the GitLab Merge request what is equivalent to a local git merge. You can choose do trigger an local command line or using the Gitlab http page therefore or sync your local repository with remote side on a Gitlab test account. Have fun trying

Not quite. A merge (or pull request) is a tool to manage feedback for a contribution via a web interface. A merge is then what can happen at the end (there are alternatives but i am not going into details here)

This children’s playground must be in Lake Wobegon, where all of the children are above average. But in this case, I think it is far above average.

Oh, no…this is getting deeper…

1 Like

Isn’t that the nature of any technology topic? (Or possibly live in general)
It is kind of what makes live fun to me.

You will not learn to understand if you dont dive in and nobody will be angry about mug on your clothes. Simply click through the explanation windows until they close, possibly without understanding anything of them. Left window shows a terminal where you can type in your commands. Type in

git commit

as often you as you want and see what happens in the graphics

I guess for me, it is designing a new electronic circuit and having it work as intended.

Ahh OK; I had to go back and re-read. I want to ask Atlassian why the thin black arrows are drawn reversed? It seems to me that they should go from C0 to C1 to C2 etc… Well anyway I am trying to step into the shallow end of the pool but it seems that the bottom of it has a steep slope…:frowning:

Some years ago I became impressed that for some reason I am much better with analog hardware than I am with software. You can reverse that statement if you wish.

I have gone to the atlassian link, and I think that I can only kinda sorta understand what they are saying. Analogy: A person first needs to understand the basics of resistance and capacitance before they can understand electronic circuit design.

From Atlassian:

If you’re a developer who has never used version control you may have added versions to your files, perhaps with suffixes like “final” or “latest” and then had to later deal with a new final version.

Holy smokes; YES. I say that only because the same applies to hardware design. “Final version” is a claim which is doomed to failure.

This is why at my last several workplaces, we have treated hardware designs just like software. We store them in Git repositories and use tags etc. to keep track. Not all paradigms are the same: hardware usually can’t be readily “merged”, but even if you don’t use branching and merging, using a VCS like Git for your hardware designs can be very handy.

1 Like

I suppose there is a big difference between small projects with 1-2 designers and larger ones. But my method of revision control is a simple date (and probably an added rev letter) in the filename. What I am doing with KiCad is to copy and rename the project folder along with the ~8 contained files, all with the same name. Doing this takes 1-2 minutes. Again…I can see that it would be more difficult if we had 10 people contributing.

I use Git even with solo projects. It’s just easier for me now. No need to constantly copy/rename things, and it encourages me to make commits (i.e. save snapshots) more often.

There is also the option to use a centralized version control system that allows for (or possibly better enforces) locking which avoids the possibility of a merge conflict to arise.

Team PCB merge is a thing we should think about for Version 7. Its a great workflow to do simultaneous component place and later simultaneous routing with associates each one assigned to a diffrent sub-circuit of the pcb. If you have enough engineering capacity, that cuts down the design time significantly