How do you version your KiCad projects?

Community
21

@Tojan I was thinking a bit more about your MAJOR.MINOR.PATCH scheme, and there are two scenarios I’m curious about:

  1. In the case where you need to make minor changes to the KiCad project that are not an actual rework/bodge–for example, you need to fix a typo in the schematic or update documentation in the project repository–are those changes also implemented by incrementing the PATCH version? (you mentioned that PATCH is only used for actual patches, so I’m wondering how all other non-PCB changes are handled)
  2. I’m wondering if your MAJOR.MINOR.PATCH scheme is used in both the prototype and production phase. Incrementing the MAJOR version on any external interface change makes sense to me for a production part where consumers of the part rely on a stable interface (enclosure tooling is already done, SW is released, etc). However, in the prototyping phase/pre-production phase, my experience has been that there are lots of minor external interface changes while the pre-production design is being validated (mechanical parts shifting due to enclosure changes, pinout changes for connectors, etc). It seems like having the MAJOR version potentially changing for each prototype build leading up to the release of a single production design would cause a lot of churn/confusion. (I think this is actually one of the complaints people have about semver in the SW world, i.e. any tiny incompatible API change causes a major version increment). Just curious if you use this same scheme in prototype vs. production, and if it’s just one of those things that requires discipline & a mindset shift to get used to.
22

@craftyjon Oh, interesting, I’m surprised the PLM will let you submit a change to an existing document without changing the rev. The anal-retentive part of me gets nervous about the idea of changing anything without changing the rev, but I guess the ECO itself documents the change history, so probably ok? :man_shrugging:

This is really similar to what I’m used to from previous jobs, and I’m trying to do something similar for KiCad projects. Are you generating these outputs in an automated way from KiCad? Do you store the P/N’s in the KiCad project or in some kind of external build tool? I’m in the process of trying to get KiBot to generate outputs like this, but I’m running into an issue exporting files with different P/N’s for schematic/PCB/etc. Just curious if you’re using another tool for this kind of release automation.

23

Yes, exactly: For the PLM, every controlled change is a new “version”, kind of like a Git repository where the only time you commit is a controlled release. So, you can have multiple “commits” that each have the same revision ID. It’s a human-controlled process to do the check that if you are doing an ECO that does not increment the board revision, it’s because you are making a change to something insignificant like a typo.

Not 100%. This workflow is one we want to use with multiple tools including KiCad, Currently KiBot is the best bet for KiCad although if you want something it can’t do, using another post-processing script may be an option (or modifying KiBot)?

24

usually this is not the case as official documentation is living in a separate repository with its own version numbers and only references to specific versions of the board. for internal documentation we usually don’t care that much and it just gradually evolves in the development branch. if there are cases, where a version number has a big bug in documentation or production data we normally just shift the revision tag to the new commit as otherwise the lot of references we use would all need to be updated as well.

not much I can’t say here as we don’t really have a production phase for boards and our development process differs probably quite a bit from normal PCB design. as our interfaces usually get defined long before the pcb-design starts the problem of to many interface-changes usually do not occur. I think the biggest MAJOR version we have now after more then five years of using this versioning is three.

But in the end it (at least in my perspective) makes not really a difference. you anyway need a new tag for the new prototype version and if the tag now is a date or has double digit MAJOR version does not really change anything.

25

For my versioning, I only revise the major number if I make major changes. I go by major.minor.revision. If I make a change that does not involve changing the stencil, I consider it a revision change. If it involves a stencil change then it’s a minor change.

26

Love the discussion. So good to see what works in the field, and how, since this is a perennial question with new answers every time it is asked! Great effort @cdwilson .

At my previous consultancy (ie. lots of 3-9 month projects for external clients) we developed a scheme that worked really nicely for us:

  • A schematic file or a PCB file is a design document, so gets versioned like they would. This scheme extended to a broad range of design artefacts.
  • Every change, regardless of significance (high granularity is encouraged), is tracked with the linearly incrementing rev created by Subversion. Only a file’s rev history in trunk matters for figuring out which is which. Eg. Rev 212 is newer than Rev 190, and the change log says what has changed. It’s up to the consumer of that log to determine significance for their particular use case.
  • Every design document is subject to “up-rev events” which change the version (not to be confused with the SVN Rev!). Basically that trigger is “are we going to share this document with someone?”. Whether that’s for publication, formal review, discussion with stakeholders, or handing over responsibility. At that point the alphabetical version of the document is increased: A → B → C, etc. And we record the release notes as a digestible summary of the change log since the last up-rev event. This version must always appear on the document itself and never leave our reach without it! Being alphabetical helped reduce confusion about what was the right “version number” significantly. Skipping letters is fine, if that helps with consistency, but going backwards is not.
  • Finally, physical PCBs are a special case. When we commit to a manufacturing run, the PCB file is up-revved as normal, but the PCB itself is also marked using the silkscreen with the order date in vYYMMDD format. This has proven extremely useful, because when we pick up a PCB, we have a trail that says this particular PCB was created with this rev of the PCB file, and this particular rev of the SCH, and this particular order to the manufacturer - oh and look, this time we specified that the manufacturer should panellise, or that time we agreed for expediency to accept HASL even though the PCB file says ENIG.
  • Note we don’t set any expectations of “backwards compatibility” - if a new version works with an old stencil or an old firmware, then that’s usually a mere coincidence. If we wanted to be backwards compatible we would want to be sure, and we generally have no good reason to expend the time necessary to be sure. Default assumption - every new version is designed to meet the new spec, not the old one as well. If an interface needs to be maintained, that would be specified.

Being a product development consultancy, wrapped around all this was whatever product branding/naming the customer wanted. So they were free to call particular versions “Gizmo v2” or “Thingy 2000” or whatever made sense for them, and we could maintain a consistent, predictable design versioning system underneath.

We also didn’t change versioning schemes between proto and prod (because it’s hard enough to see the transition as its happening, let alone with enough warning to switch schemes!), but we were a little cute about it - every board that was not to go into service we coloured with our brand of blue. Only when we were happy for our customer to let it rip in the field did we ask what colour they wanted it to be (default green). Then it became there’s and they could order production. Saved a lot of those awful “but it wasn’t ready!” design dramas.

The push to shove SW practices in to everything that is not SW is unavoidable, and there’s a lot of upside if it’s done well. So great to read how people are navigating (or not!) the semver-for-everything and PLM-driven versus programmer-driven versus EE-driven workflows.

1 Like
27

So in that case, you labeled the PCB silkscreen “Gizmo v2” or “Thingy 2000” before sending it off to the fabricator ? And I reckon you saved that label in subversion too?

Thank you for sharing your thoughts and workflow.

28

Love this idea!

Just to clarify, what you’re referring to as the version (A → B → C) would get put into the “Rev” field in the drawing’s title block? (If so, this is basically what ASME Y14.35 would traditionally refer to as “Revision Letters”.)

Is the “SVN Rev” also included in the released document?

If you’re aware of other places where this question has been asked, could you provide links to them?

29

Yes! Or to be more precise, labelled the PCB in the way they liked - our traceability remains intact, so if they want the branding there or not, we’d accommodate. As you suggest, it’s more important that we record the relationship in version control.

Yes, precisely. If Subversion hadn’t already used the term “rev”, we would have been happy to reserve it for the purposes you describe. As you indicate, that terminology is well established in drawings-land. Basically we’d use “SVN Rev” as internal terminology because it really was specific to our design practice. “Revision Letters” and variations on that term are as you describe, and since many of our stakeholders were used to referring to issues of documents as “versions”, that was the outward-facing terminology we’d use.

No. We reserved it for internal use to reduce confusion. The mapping from version to SVN Rev was easy for us to simply look up, so it would have been redundant, as well as a potential source of confusion.

Funnily enough, to turn this discussion upside down - the one place our stakeholders did see the SVN Rev was in the firmware version. It was auto-generated from some developer specified version string (typically major.minor or similar) concatenated with the SVN Rev. This was really important, because firmware got “released” (aka, escaped our careful grip) far more frequently - we’d have test devices or customer samples or whatever running some version of firmware, and we needed the extra precision because it could well be a cut of the code base in-between official releases.

Alas, no. That’s what prompted me to thank you so earnestly! It gets discussed in private in every team I’m part of, and every now and then someone learns Git for the first time and publishes a discussion-free tutorial of how it’s the best thing ever for hardware. But in a shining example of my criticism of our industry for rarely conducting deep explorations of best practice compared to the SW world, I can’t recall a public discussion as good as this one.

30

Lots of interesting ideas here. The use of Git submodules is new to me and not obvious how it would be done. There is an example from John’s Basement where he used some libraries of schematics as subroutines that made me think of both the possibilities and the complexities of trying to manage change across it all. See: KiCad 5 #17 Hierarchical Labels & Pins - YouTube

In much of the traffic here I think there is a vagueness in vocabular which I resolve like this.

A Printed Circuit Board (PCB) is a (usually) fiberglass and copper thing with out components soldered on it.
A Printed Wiring Assembly (PWA) is a PCB with components soldered on to it. (Never use PCA printed circuit assembly as it is too close to PCB)
A schematic defines both a PCB and how to build the PWA. It may even need to call out firm ware to load and a factory test procedure.
If you build two different PWAs from the same PCB you need two different schematics. Each schematic has a unique part number. This is also why I never put component values on a PCB silk screen. You can only be wrong. Each of the two or more schematic has a title descriptive enough to differentiate the reason for the unique part numbers and unique PWAs they define.

The PCB has a part number. Any change that impacts forward or backward compatibility requires a new part number. A revision change (or version) is really a part number change. Change is expensive. DON’T make changes that are not required. If changes to a part ( a PCB or a PWA or a schematic) are required then general you cannot user them interchangeably.

A schematic has similar requirements but as someone above mentioned you might improve the notes or reference text (fix spelling errors etc) and have a schematic which still defines the same PWA when done. Here the higher or later version would help you be sure you have the newest schematic in hand and can destroy older version so that they do not haunt you.

When you release from your custody something, a PCB file, PWA bill of material, Schematic to ANYONE else you must be versioning it or unhappiness will result. It is horrible and unreliable to have to ask people to look at dates on files to untangle changes.

And their is a very difficult problem of the case where older versions of PCB build up into PWAs are reworked to reflect circuit changes put into newer PCBs and PWAs. What do you mark them? You must mark them so that they can be distinguished but deep inside we know a rework only approximates the changed PCB and PWA so marking to the revised PCB and PWA is ill advised.

All problems that a beginner may not anticipate.

Hope this helps.

31

I guess we will agree to disagree on this, I’ve never heard people use “PWA” in my corner of the industry.

This is not my experience. How to build a PWA/PCA is captured in a separate drawing, called an assembly drawing, that is based on the PCB CAD (not the schematic). Additional procedures like firmware loading are typically documented either as notes on this drawing, or as separate revision-controlled procedures with their own part numbers. Not saying you are wrong, just that there are multiple ways of doing things.

Kind of – you need two different BOMs / PWA part numbers. There are ways of driving these from a single schematic (although in KiCad at least this is a manual process)

Agreed – reworked boards should not be relabeled as a newer revision. They should be marked specifically as reworked using some methodology that is documented in the PLM system alongside the rework documentation, in my opinion. So for example we have rework instructions that say to apply a certain color dot of paint pen, or apply a special additional label, etc.

32

I’ve never heard it being called PWA and I’m not sure if I’ve heard it being called PCA either. I’m used to the term PCBA. Or PCB Assembly.

33

I’ve used both; just shortened to PCA recently so that all the category names are 3 characters.

34

Regarding, “I’ve never heard it being called PWA …”

Yup it is an unusual acronym but because it has much less chance of confusion with PCB it has become my favorite. Language is our tool and we should use good tools when we can.

35

FWIW, I’ve found this response from Jack Crawford (Director of Certification and Assembly Technology for IPC) helpful in clarifying IPC’s recommended usage of some of these terms:

This question has been discussed numerous times at IPC meetings and usually enables a fair amount of emotion.

All of the following are possible uses, depending on your age, geographic location (slang usage), and where/how you got your training. I’m sure there are more.

PB - printed board. the most generic term for a bare board

PWB - printed wiring board, one of the first uses when the issue was only a point to point connection.

PCB - printed circuit board, where the width, side to side and multi-layer relationship(spacing) of conductor runs has or is designed to have a specific effect on circuit operation other than just a point to point connection. Circuit impedance is a primary issue. In approximately 1999 the IPC Technical Activities Executive Committee made a mandate to only use the term PCB for all new document development because more often than not the printed circuitry design will have an impact on function.

PWA - printed wire assembly - older use

PCA - printed circuit assembly - logical to use with the 1999 change to PCB.

PCBA - printed circuit board assembly - multiple requests/comments (strong push) from users and technical committees in Asia and Europe to use this as the preferred term.

Embedded active or passive components opens up a whole new range of possibilities as well.

However, I think this last bit is especially salient:

While it would be good to have a single term (or pair of terms for bare boards and assemblies) reality is that there are many IPC documents of various age using different terms and many more book and magazine article authors, conference lecturers, etc., that pretty much use whatever term they are most comfortable with.

If preparing a document; it would be appropriate to use a term that most of the expected users would understand. In the world of electronics technology, it would seem that most users should be able to understand the content when any of these terms are used.

It seems like the terminology has changed over the years and can vary depending on audience and region. It’s a good reminder for me that my own views on “the right way to do things” is heavily influenced by the groups I worked with in the past and the specific corner of the industry I was in.

At one company I worked for, we had a separate rev-controlled doc called a “PCAMAP” (PCA manufacturing assembly procedure) that detailed assembly requirements like loading firmware.

We also used a single schematic document with BOM attributes that would result in a unique BOM for each assembly variant. This was in the Cadence tools, but now I’m doing something similar using part attributes in KiCad using KiBot (KiBot will even generate customized schematic PDFs for each assembly variant with a red “X” crossing out parts that are DNP on that variant)

100% agree on this :+1:

1 Like
36

Regarding: [quote=“cdwilson, post:35, topic:36898”]
We also used a single schematic document with BOM attributes that would result in a unique BOM for each assembly variant. This was in the Cadence tools, but now I’m doing something similar using part attributes in KiCad using KiBot (KiBot will even generate customized schematic PDFs for each assembly variant with a red “X” crossing out parts that are DNP on that variant)
[/quote]

Can you point us to a resource for this methodology.
In 2019 I learned how to use the Altium “Variant” methodology (from an excellent
Robert Feranec Youtube series ) which sounds a lot like what you describe.
By setting up variants you created the different schematics and all other document creation were driven through a uniform process. I am very interested to learn more.

Caution to all. Their is an argument against all this and it would be that as we concentrate this functionality into the Schematic capture process, that if there is some aspect of manufacturing not also captured, then the system remains broken in the Schematic capture. An example of problem: is that we may be trying to control (or document) manufacturing steps better left to the discretion of a manufacturer.
Meaning it is better to document what the end PWA should be and not how to get there.

Specific example of what can go wrong I just faced? In the real world when working at the schematic level we may know we are going to hand solder some SMT parts in our process (In a hypothecia case I am perhaps hand building only a few assemblies) and so choose the KiCad PCB footprint symbol for hand solder.

What shall we do?
The best we can do may be to warn beginners to our profession (or hobby) about the possibilities and muddle along ourselves.

Regarding “PWA - printed wire assembly - older use”
Yup.
I am older (63) and I adopted this methodology way before 1999. I advised this vocabular because I am also older and may not distinguish between PCB and PCBA. With luck everyone here will become older too and some will find discrimination of that last “A” difficult. As someone creating schematics which will drive the documentation process we are in a position to head off these problems.

Again,
Language is our tool and we should use good tools when we can.

1 Like
37

@ForrestErickson sorry, was on vacation this past week and didn’t get a chance to reply until now.

I’ve posted a quick response below to your question about assembly variants to get you pointed in the right direction, but I realized that we’re quickly taking this thread off-topic from it’s original focus on versioning. If you’ve got follow up questions specifically related to working with variants in KiCad, can you start a separate topic? I think that will allow a more focused continuation of the conversation without derailing this one any further.

If you’re just looking for a way to generate separate BOMs for multiple variants (but not generate separate schematic PDFs for each variant), you can use the KiBoM plugin for KiCad. The way I’ve used this in the past is to define a bom.ini file in the project directory and use what KiBoM calls “complex variants”. In the bom.ini file, you can define the BOM variants in the board_variant field.

In the example below, there are two assembly variants (FCD-000035 & FCD-000046):

[BOM_OPTIONS]

(FYI, this is just a snippet, not a complete working config)

; Specify output file name format, %O is the defined output name, %v is the version, %V is the variant name which will be amended according to 'variant_file_name_format'.
output_file_name = %O_bom_%v%V
; Specify the variant file name format, this is a unique field as the variant is not always used/specified. When it is unused you will want to strip all of this.
variant_file_name_format = _(%V)
; Complex variant processing (disabled by default)
complex_variant = 1
; Default PCB variant if none given on CLI with -r
board_variant = "FCD-000035,FCD-000046"

Then, in the schematic, you define separate fields for each variant (variant_name:field_name).

image
image1706×1454 310 KB

When you run KiBom, it will generate two separate BOM files–one for each variant–where the value, description, MPN, etc for U1 are different for each assembly variant in the CSV file.

If you want to generate different BOM files AND different PDF files for each assembly variant, I don’t think it’s possible to use KiCad alone. I’m using KiBot now (instead of KiBoM) which is able to generate different PDF schematics for each assembly variant using the same “complex variants” fields I described above. You’ll get PDFs with red “X” marks across all the components that should not be populated for that variant. Here’s an example of what it looks like:

image
image564×532 24.2 KB

To get this working in KiBot, you need to define a config.kibot.toml file in the project directory that defines the variants and outputs a schematic for each variant

(FYI, this is just a snippet, not a complete working config)

variants:
  - name: FCD-000035
    comment: FCD-000035
    type: kibom
    file_id: _FCD-000035
    variant: FCD-000035
    pre_transform: _var_rename
  - name: FCD-000046
    comment: FCD-000046
    type: kibom
    file_id: _FCD-000046
    variant: FCD-000046
    pre_transform: _var_rename

outputs:
  - name: schematic_pdf
    comment: Export the schematic to PDF
    type: pdf_sch_print
    dir: +/Schematic
    options:
      dnf_filter: _kibom_dnf_BOM
      frame: true
      monochrome: false
      output: "%f-%i%I%v.%x"

When you call KiBot to generate the outputs, you can specify the specific variant using the -g variant=<variant_name> flag (e.g. -g variant=FCD-000035).

2 Likes
38

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.