Misleading "Update footprints" text in "Update PCB from Schematic"

[eelik]

The "Update PCB from Schematic" dialog - opened from eeschema or pcbnew - has an option "Update footprints". The UI text is misleading. I have seen at least two threads in the user forum where a poster was confused by that, trying to update footprint(s) on a board after modifying the footprint module files.

The confusion comes from using the word "update" in two completely different contexts with footprints. What the "Update PCB from Schematic" dialog actually does is change (or not) the footprints if the footprint associations, i.e. footprint names, have been changed in symbols of the schematic. I think the UI text should reflect that. The word "update" should in my opinion be reserved for updating from the changed library file.

I would even go as far as to say that the dialog UI text could be "Don't change footprints" or "Keep old symbol/footprint associations" or something like that, and the default would be not selected.

In the minimum it should have a tooltip text which explains what it does. Now none of the Options has a tooltip.

Application: Pcbnew
Version: (5.1.3-7-g8373e91a1)-1, release build
Libraries:
    wxWidgets 3.0.4
    libcurl/7.61.1 OpenSSL/1.1.1 (WinSSL) zlib/1.2.11 brotli/1.0.6 libidn2/2.0.5 libpsl/0.20.2 (+libidn2/2.0.5) nghttp2/1.34.0
Platform: Windows 8 (build 9200), 64-bit edition, 64 bit, Little endian, wxMSW
Build Info:
    wxWidgets: 3.0.4 (wchar_t,wx containers,compatible with 2.8)
    Boost: 1.68.0
    OpenCASCADE Community Edition: 6.9.1
    Curl: 7.61.1
    Compiler: GCC 8.2.0 with C++ ABI 1013

Build settings:
    USE_WX_GRAPHICS_CONTEXT=OFF
    USE_WX_OVERLAY=OFF
    KICAD_SCRIPTING=ON
    KICAD_SCRIPTING_MODULES=ON
    KICAD_SCRIPTING_PYTHON3=OFF
    KICAD_SCRIPTING_WXPYTHON=ON
    KICAD_SCRIPTING_WXPYTHON_PHOENIX=OFF
    KICAD_SCRIPTING_ACTION_MENU=ON
    BUILD_GITHUB_PLUGIN=ON
    KICAD_USE_OCE=ON
    KICAD_USE_OCC=OFF
    KICAD_SPICE=ON

Application: Pcbnew
Version: (5.1.0-1383-gee1be14b6), release build
Libraries:
    wxWidgets 3.0.4
    libcurl/7.61.1 OpenSSL/1.1.1 (WinSSL) zlib/1.2.11 brotli/1.0.6 libidn2/2.0.5 libpsl/0.20.2 (+libidn2/2.0.5) nghttp2/1.34.0
Platform: Windows 8 (build 9200), 64-bit edition, 64 bit, Little endian, wxMSW
Build Info:
    wxWidgets: 3.0.4 (wchar_t,wx containers,compatible with 2.8)
    Boost: 1.68.0
    OpenCASCADE Community Edition: 6.9.1
    Curl: 7.61.1
    Compiler: GCC 8.2.0 with C++ ABI 1013

Build settings:
    KICAD_SCRIPTING=ON
    KICAD_SCRIPTING_MODULES=ON
    KICAD_SCRIPTING_PYTHON3=OFF
    KICAD_SCRIPTING_WXPYTHON=ON
    KICAD_SCRIPTING_WXPYTHON_PHOENIX=OFF
    KICAD_SCRIPTING_ACTION_MENU=ON
    BUILD_GITHUB_PLUGIN=ON
    KICAD_USE_OCE=ON
    KICAD_USE_OCC=OFF
    KICAD_SPICE=ON

[Nick Østergaard (nickoe)]

Maybe just add a tooltip that documents it only updates if the footprint reference is different in the schematic and does not reload from the footprint lib. Maybe this should be am additional option?

[eelik (eelik)]

A good tooltip is sometimes a life saver, but in this case it wouldn't be too difficult to find a good text which is immediately visible. Quite many software users try things without reading tooltips - why not make it unambiguous and clear at the first sight. A UI talking about "updating footprints" with two different meanings is deceptive. It could easily be avoided.

I, too, remember thinking at first that the "update" in this dialog meant updating from modified footprint files. It wouldn't be far fetched to have that as an additional option, as kind of a side effect of updating the board from schematic. But does it really belong there?

[Jeff Young (jeyjey)]

A *does* do an update, but only if the IDs don't match. Which is a best unexpected, and at worst might appear random.

Why not just change the functionality to really be "update", rather than changing the text to match the current (somewhat odd) behaviour?

[Jeff Young (jeyjey)]

^A^It^

[jean-pierre charras (jp-charras)]

The current behavior is good.
Changing the text to match the current behavior is good for me.

I am strongly opposed to blindly update all footprints: this is the best way to break a design.
For many reasons, the footprints on the board can be slightly different from the library.
For instance after updating a library.
It can easily happen when a board is slightly modified 2 years later...
We already know that with Eeschema.
And most of time because a footprint can be slightly modified on the board (pad shape, 3D model ...) for mechanical or electrical reasons.

[eelik (eelik)]

jp's reasons are compelling enough. I would add another point of view. Users should learn to use the real update dialog anyways. When they do, they don't need this kind of additional update mechanism in another dialog. And if they don't know about the real update dialog they'll try to use this half-working solution and wonder why it breaks things or doesn't have necessary options - the whole update dialog can't be doubled here anyways.

The problem which some people had - at least I suppose so - is that they didn't know about the real update dialog, tried to use this "Update footprints" option which they naturally found (because it's promptly visible in a dialog which they had already used) and then wondered why it doesn't work.

[eelik (eelik)]

"*does* do an update, but only if the IDs don't match. Which is a best unexpected, and at worst might appear random."

Wow. What is this ID? I based my comments on the observed behavior. Even though I'm above an average user, at least above a novice, in knowledge of the internals it looks like I still don't understand what this actually does.

Is this an advanced option which shouldn't normally be used?

[Jeff Young (jeyjey)]

@JP, fair enough. I'll look into better text.

@eelik, the ID is the library nickname followed by ':' followed by the footprint name. If that changes we have no option other than to leave the footprint as-is (not matching the ID), or fetch a new copy from the library (which is equivalent to updating).

[eelik (eelik)]

OK, thanks for the explanation. I thought of it just as the "name" of the footprint, although I understand that technically speaking the ID can be changed even though it refers to the same footprint file. Basically I understood the process correctly - if the ID is changed the footprint will be loaded to the board again even when it's the same file.

This is already a bit offtopic and even though this isn't a user support forum, could you still clear up? If the Update footprints option is unchecked, does KiCad update the IDs in the board to match those in the schematic, but without reloading footprints from files?

If my understanding is correct, the option is useful for situation where the fp-lib-table has been changed so that there are for example new nicknames, but the actual footprints haven't changed. Otherwise I don't see much point for it - it wouldn't be good if the fp IDs in the schematic and in the board don't match, and after that when even one footprint association was changed the user should use the Update option and everything would be changed anyways.

[Jeff Young (jeyjey)]

Rather than answering @eelik's question, I'd like to come up with a dialog where eelik doesn't need to ask it.

Please comment on the attached.

[Wayne Stambaugh (stambaughw)]

@Jeff, I'm not sure either of these are clear. Prior to the latest changes, footprint associations were updated by reference or time stamp. I'm not sure how to word time stamp so that users will understand the difference. That being said the top radio button (time stamp) text may make more sense if you use "Update footprint associations by symbol reference changes". Maybe the bottom radio button should be worded "Update footprint associations by existing reference". Maybe some additional information as to why you would want to use either choice in a tooltip may be a good idea as well.

[eelik (eelik)]

I would be happy with those. Also the Matching method is clearer, I can actually understand what it means now, although all these options need some thinking and knowledge. Tooltips are still important. The hint about the use case in Matching method, "after full reannotation", is useful. Otherwise the wording of the tooptip could be improved.

I tested what the Update (or Replace) footprints option does. I don't understand what use cases it actually serves. As I said, when the option is checked next time, the changed footprints will be reloaded anyways even when they were ignored in previous update. And if it's kept unchecked, the schematic and the board aren't in sync anymore, and why to change associations in the schematic if they won't be used? If there's some use case, put it in the tooltip or othewise make it more clear what it does and why. The immediately visible text in your proposition is good because it's descriptive and must be short and to the point.

[eelik (eelik)]

(I noticed Wayne's comment only after mine.)

By reading the Jeff's proposition for Match Method I actually can understand what happens. If a reference is changed in the schematic, it will be changed in the board, too. And the other option makes the footprint to be associated to the symbol which has the same reference as the footprint. Does it matter what mechanism it uses internally? Does the user have to know about timestamps? If yes, maybe just add it to the text:
"Update...references (using timestamps)"
or put it in the tooltip.

But for the bottom radio button Wayne's wording sounds good.

Anyways, I doubt if most users know or even want to know what KiCad uses internally, and I don't think the immediately visible user interface should reveal internals of the software to the user unless necessary.

_______________________

Can the two radio buttons have their own tooltips - now they share the same? It would be easier to read and understand them if each option would have their own.

[eelik (eelik)]

"I tested what the Update (or Replace) footprints option does. I don't understand what use cases it actually serves."

To be clear: I don't understand why or when the checkbox should be left unchecked. The default is checked and it's of course clear why. When I change a footprint association I want it to be reflected in the board.

[eelik (eelik)]

I just noticed that the current tooltip of the Match Method is another source of confusion for me. Is it actually correct? Should it be vice versa? And why would "full schematic reannotation" matter if the associations are found by timestamp in the default option? Is full reannotation somehow completely different than changing only some of the reference designators?

[Jeff Young (jeyjey)]

> To be clear: I don't understand why or when the checkbox should be left
> unchecked. The default is checked and it's of course clear why. When I
> change a footprint association I want it to be reflected in the board.

The above strikes me as a good question. If you’re working on the schematic of a board that you don’t want changed, then you’re not going to do an Update PCB at all. Under what conditions would you want to Update the PCB but NOT reflect any changes you had made in Cvpcb?

[Jeff Young (jeyjey)]

I've merged some fixes based on the feedback. The Janitor will therefore close the bug, but if anyone comes up with any improvements please re-open.

[KiCad Janitor (kicad-janitor)]

Fixed in revision 1ea9ad05bc44e48066ccf8c956ce8876d3f05b3c
https://git.launchpad.net/kicad/patch/?id=1ea9ad05bc44e48066ccf8c956ce8876d3f05b3c

[Nick Østergaard (nickoe)]

@Jeff in #16 , if you just added som new symbol with footprint in eeschema and would lile that in the pcb, but you don't want to update the footprint of previously imported footprints just yet.

[eelik (eelik)]

I tried to read from diffs, so I don't have the big picture, but why mention Cvpcb in the tooltip? Doesn't that lead to think that if Cvpcb - that name isn't, by the way, used in the UI anymore at all - is not used to change the associations but they are changed by other means, then this option should not or need not be used?

Having this option checked is the default and should probably be used almost always, so only the exception could be stated in the tooltip, and checked/unchecked state must be clear from the text.

[eelik (eelik)]

"Normally footprints on the board should be changed after footprint associations in the schematic have been changed. Uncheck this only if you don't want to change existing footprints on the board."

Using the word "change" is also compatible with how it's used in pcbnew in Change Footprints.

[Wayne Stambaugh (stambaughw)]

The reason there are two ways to update the footprint association is pretty straight forward. When the netlist is imported into pcbnew, the symbol time stamp (unique identifier?) is used to track reference changes between the schematic and the board. If an existing symbol is deleted from the schematic and new symbol is is given the same reference, the time stamp information is lost so pcbnew will remove the existing footprint and add a new footprint with the updated symbol time stamp which may not be what you want. By selecting the second option, the reference in the board is used and the time stamp is updated to match the new symbol. In short, option 1 updates footprint associations and references by time stamp and option 2 update footprint associates and time stamp by reference. There are valid reason to do both.

[eelik (eelik)]

Wayne's latest comment above confirms my suspicion that the old tooltip gives wrong information. It has nothing or little to do with "full schematic reannotation".

Here's Jeff's new proposition:

"Footprint references are normally updated to follow edits in the schematic.\nHowever, updating footprint associations usually works better after re-annotating the schematic.\nFor best results, update footprint references before re-annotating, then re-annotate, and then update footprint associations."

This may be correct, but it's difficult to understand. I feel I fully and easily understood Wayne's explanation, but it's too long for a tooltip :( And Jeff's text looks like it still talks only about re-annotation, not about changing the symbol and loosing the timestamp (i.e. "loosing the normal connection between the symbol in the schematic and the footprint on the board" to use more understandable terms.)

Additionally the new tooltip doesn't give any explicit information about using the two options or if it does, it does it cryptically.

How about this:

"The first option should be used when new symbols have been added or existing symbols re-annotated.\n\nThe second option should be used if symbols have been deleted and re-added or replaced but references and footprint associations kept as they were."

I assume that if an old symbol is replaced with another symbol and the footprint also changed at the same time, the first option should be used because the old footprint should be replaced on the board, too.

[Jeff Young (jeyjey)]

I like eelik’s improvement’s to the checkbox tooltip, although I’ve massaged it a bit more. How about:

"Normally footprints on the board should be changed to match footprint assignment changes made in the schematic. Uncheck this only if you don't want to change existing footprints on the board.”

I don’t think we’re quite as close with the radio button tooltip. Here’s another straw man which attacks the problem from a different angle:

“The first option uses the existing links between symbols and their footprints to update the footprints based on changes made to their symbols. The second option uses the symbol and footprint references to establish a new set of links between symbols and footprints."

[eelik (eelik)]

Whatever the radio button tooltip text is, it's good to add extra newlines between two parts. That way it visually corresponds with the two options, top and bottom.

My suggestion tells only when/why to use the option. Your suggestion tells what it does. Would the text be too long if they were combined?

On the other hand the UI text of the radio button should already tell what it does, so the tooltip would serve better if it would tell when or why to use an option.

I think there's no escaping the fact that understanding these requires some amount of experience or background knowledge. But we should think about novice users who do something with the schematic and then try to update the board. Telling both what the option does and when to use it would be the best combination, I think.

[Jeff Young (jeyjey)]

Hi Eeli,

More newlines is a good idea.

The reason I moved away from telling when to use it is that both your reasons and my original reasons are correct: ie: there are several reasons for using each one, and it was all getting a little messy.