obsoleting mechanism

[failiz]

The obsoleting mechanism is documented in https://github.com/fritzing/fritzing-parts/blob/master/CONTRIBUTING.md, but I think that it still misses some information.
This is the paragraph with the instructions:

To use the update mechanism: The new part should have a different file name (TODO: check if that is really necessary) The old part should be moved to the obsolete folder if it is not available anymore, or if it has severe errors. Do not change the moduleId of the old part. The new part should have a new moduleId, for example by adding a hash to the part name, or using a different has. Add a 'replacedby' attribute to the version tag of the old part. The attribute value should be the new parts ID: '''4'''

First, most of the obsoleted parts have been modified to include the "//obsolete//" prefix before the family property. This is not documented.

Second, I do not think that a different file name is necessary. In fact, there is a pot_slider.fpz in the core folder and the obsolete folder. In any case, I would change the filename when moving the part to the obsolete folder as this will allow having several versions of obsolete parts. In any case, clear guidelines should be reported to change the name of the files. I would suggest adding an "_vX", where X is the version of the part as specified in the version property.

Third, the same applies to svg files, which is more tricky as there are not moduleIDs. Should we change the svg when moving them to the obsolete folder (and changing all the obsoleted parts to point to the renamed svgs) or should we create a new filename for the new svgs?

Fourth, there is a script in the folder, but I think it does not does that all these changes yet. In any case, maybe the script should be mentioned in the documentation if it is useful.

This issue was originated by a discussion to fix the potentiometer symbol, see full discussion in the forum

[KjellMorgenstern]

The defining criteria for an obsoleted part should be the existence of a 'replacedby' attribute.

Please also see
https://github.com/fritzing/fritzing-parts/blob/develop/scripts/obsolete.py
I created the script since there are quite a number of steps when obsoleting a part. It is still a bit rough.

1. The //obsolete// prefix is a hack to avoid listing obsolete parts as alternatives via the inspector. This should be fixed in Fritzing, so obsolete parts don't show, no matter of the family property.

2. Basically, I don't change the filename when obsoleting a part. Instead, the new part should have a new filename, for example with a increase _vX marker, or simply a new hash suffix.

3. Right now I think obsoleting only a svg is not possible. Instead, the affected part should be obsoleted (possibly together with problematic svg files)

4. I hope for the script to help standardize the process.

[failiz]

Thanks Kjell. However, I think that the script obsoletes all the svgs of a part (icon, bb, sch and pcb). This could be necessary in some cases, but it is not needed with a lot of other parts where there is only an issue in one of the svgs. This will create a lot of parts with different names that are in fact the same.

python3 obsolete.py -s ../core/pot_big.fzp pot_rotary_16mm
Need at least python 3.8. Switching to dry run.
Dry run, no file changes will be written.
('git', 'mv', '../core/pot_big.fzp', '../obsolete/pot_big.fzp')
('cp', '../svg/core/icon/potentiometer.svg', '../svg/core/icon/pot_rotary_16mm_64b2899_002.svg')
('git', 'mv', '../svg/core/icon/potentiometer.svg', '../svg/obsolete/icon/potentiometer.svg')
('git', 'add', '../svg/core/icon/pot_rotary_16mm_64b2899_002.svg')
set layer image to icon/pot_rotary_16mm_64b2899_002.svg
('cp', '../svg/core/breadboard/potentiometer.svg', '../svg/core/breadboard/pot_rotary_16mm_64b2899_002.svg')
('git', 'mv', '../svg/core/breadboard/potentiometer.svg', '../svg/obsolete/breadboard/potentiometer.svg')
('git', 'add', '../svg/core/breadboard/pot_rotary_16mm_64b2899_002.svg')
set layer image to breadboard/pot_rotary_16mm_64b2899_002.svg
('cp', '../svg/core/schematic/basic_poti.svg', '../svg/core/schematic/pot_rotary_16mm_64b2899_002.svg')
('git', 'mv', '../svg/core/schematic/basic_poti.svg', '../svg/obsolete/schematic/basic_poti.svg')
('git', 'add', '../svg/core/schematic/pot_rotary_16mm_64b2899_002.svg')
set layer image to schematic/pot_rotary_16mm_64b2899_002.svg
Warning: ../svg/core/pcb/jumper_3_200mil_pcb.svg not found. Ignoring
replace moduleId="3234DFDC00PotentiometerModuleID"
with moduleId="potrotarba34a7447eea447f8be0ed34e443e5cd"
('git', 'add', '../core/pot_rotary_16mm_64b2899_002.fzp')
('git', 'add', '../obsolete/pot_big.fzp')

In addition, in the case of the potentiometer, only the svg of the schematic needs to be replaced (maybe we will modify other views but they are minor changes). In fact, some of the other svg files that the script is moving to the obsolete folder are used by other parts. Those parts will still work as the svg files will be in the obsolete folder, but it will make a big mess. In fact, if I run this script for the 5 potentiometers in the core, we will end up with 5 different svgs that are equal in the core folder.

Finally, there are some cases where the file in the core is already in the obsolete folder. For example, pot_trimmer_6mm.fzp. Thus, you cannot copy it to the obsolete folder directly, you need to rename it. Currently, the script gives an error:

python3 obsolete.py -s ../core/pot_trimmer_6mm.fzp pot_trimmer_6mm
Need at least python 3.8. Switching to dry run.
Dry run, no file changes will be written.
Traceback (most recent call last):
  File "obsolete.py", line 206, in <module>
    sys.exit(main())
  File "obsolete.py", line 131, in main
    raise Exception("Error: destination already exists %s " % obsolete_fzp)
Exception: Error: destination already exists ../obsolete/pot_trimmer_6mm.fzp

I think I will obsolete the potentiometers manually to have a cleaner repository.

"The //obsolete// prefix is a hack to avoid listing obsolete parts as alternatives via the inspector. This should be fixed in Fritzing, so obsolete parts don't show, no matter of the family property." Ok, just to be sure. Should we still use this hack for now until we fix this in Fritzing?

[failiz]

And I just noticed that there is a problem with the moduleID that generates:

replace moduleId="3234DFDC00PotentiometerModuleID"
with moduleId="potrotarba34a7447eea447f8be0ed34e443e5cd"

The new moduleID needs to finish in PotentiometerModuleID. If not, the properties of the part cannot be changed in the inspector as the suffix is used to set the editable properties based on the resorces.xml

[KjellMorgenstern]

Thanks, for the feedback

1. The script could take a "view" parameter, if we already know beforehand which view/svg will need changes. It would then only copy the needed svg

2. In case of a name collision... this is only a quick guess, but maybe: There might already be a problem: Since Fritzing determines the folder automatically, it might have been picking up the /svg/core file all the time instead of the /svg/obsolete file, which probably resulted in messed up circuits. Again, only a quick guess, maybe it was picking up the correct pot_trimmer_6mm file all the time. I think there is not much to do here, user must resolve name collisions.

3. About the suffix... I think this is a bit of a smell in the parts format, encoding such things in an ID is not a good idea. Suffixes which need to be preserved can be seen in moduleidnames.cpp . I think using random suffixes like "alps-starter-pot9mm" as used in resources/properties.xml triggers more problems, and such parts need to be fixed. So, I'd modify the script to preserve known suffixes

4. Yes, we should use the hack. I think it doesn't cause harm. Once this is fixed in Fritzing, it will be just one quirk less to remember when obsoleting parts.

[failiz]

"The script could take a "view" parameter, if we already know beforehand which view/svg will need changes. It would then only copy the needed svg"
This would be great. The option would be an svg (or several svgs in different views) and the script would modify all the parts that are using this (or these) svgs.

"In case of a name collision... this is only a quick guess, but maybe: There might already be a problem: Since Fritzing determines the folder automatically, it might have been picking up the /svg/core file all the time instead of the /svg/obsolete file, which probably resulted in messed up circuits. Again, only a quick guess, maybe it was picking up the correct pot_trimmer_6mm file all the time. I think there is not much to do here, user must resolve name collisions."
The collision is in a fzp file, not in a svg fil. The moduleID is still different even if the file name is the same. The script just needs to generate a new filename for the file copied to the obsolete folder.

"About the suffix... I think this is a bit of a smell in the parts format, encoding such things in an ID is not a good idea. Suffixes which need to be preserved can be seen in moduleidnames.cpp . I think using random suffixes like "alps-starter-pot9mm" as used in resources/properties.xml triggers more problems, and such parts need to be fixed. So, I'd modify the script to preserve known suffixes"
I agree that the alps-starter-pot9mm is not a good suffix, and I will fix it in my upcoming PR. In fact, this caused a bug #323. ''

"Yes, we should use the hack. I think it doesn't cause harm. Once this is fixed in Fritzing, it will be just one quirk less to remember when obsoleting parts."
Great. I will do that.

[vanepp]

It looks like I get to be "Someone" (as in Someone should document parts obsoleting) as I need to obsolete the Dual_VNH2SP30_Motor_Driver part. I'll add the //obsolete// to that. As well I think it would be wise to require the replacedby in the version property (which may require adding a version property to the fzp file being obsoleted if there isn't one already present, but I don't think that should cause a problem.) I'm also inclined to enforce the statement in the parts format file document

"But it is important to note that within a part, a connector's name and id attributes must be unique—that is, no two connectors in a given part should have the same id or the same name."

Since replacedby can be specified for the name field, that may be the reason for this requirement (I suspect duplicate names will cause problems with replacedby but have not yet tried it to see!) The other possibility is thought to be that if the properties of two parts are identical Fritzing will compare connector name fields in order to tell two parts apart.

"I would suggest adding an "_vX", where X is the version of the part as specified in the version property."

I'm in favor of just adding "_X" where X is the number in the version field, however there is one wrinkle I can think of: a part with multiple active versions. An example is the WeMos D1 mini. We have two in core parts (male and female headers) the pcb hole size is wrong (0.036in instead of the standard 0.038in for a 0.1 header) and it doesn't meet the graphics standards so should be fixed and obsoleted eventually. However there is now a new hardware revision from WeMos (looks to be V4.0) that adds a I2C 2mm grove connector to the board. At the same time there are still lots of D1 mini knockoff boards (without the extra I2C connector available on Ebay and elsewhere. I think that means we should keep the corrected original version of the part (upgraded after obsoleting to meet graphics standards) and add a new version for the new WeMos part. I think we should only be obsoleting (which really isn't an accurate term except for things made by the parts factory such as headers and ICs) that are broken in some way. As has been pointed out to me, people still have parts that are no longer available in their junk boxes and/or can buy them on ebay. The Dual motor driver is a case in point, it is no longer sold by Pololu, but is still useful as a Fritzing part.

[mMerlin]

It has been some time since I looked at what is needed to obsolete a part. I think that replacedby will work by just specifying the connector without the name. Both name and id can be used, but only one is needed to be functional, as long as that one is unique. It is just more readable to include the name.

[vanepp]

I'm hoping (but haven't tried yet) this will work to replace both the connector number and the name.

original

<connectors>
    <connector type="female" id="connector130" name="1INa">
        <description>Clockwise Input 1</description>
        <views>
		
to

<connectors>
    <connector type="female" id="connector130" replacedby="connector1" name="1INa" replacedby="Pin 2">
        <description>Clockwise Input 1</description>
        <views>

This changes the connector number from 130 to 1 and the name from 1INa to Pin 2. The new fzp file equivalent pin looks like this (for reference)

<connector id="connector1" type="male" name="Pin 2">
  <description>1INA Clockwise Input 1</description>
  <views>

I'm also wondering (and will have to test) what will happen with parts that change pin numbers between views (there are a few in core parts) like this made up example

    <connector type="female" id="connector130" replacedby="connector1" name="1INa" replacedby="Pin 2">
        <description>Clockwise Input 1</description>
        <views>
            <breadboardView>
                <p svgId="connector130" layer="breadboard"/>
            </breadboardView>
            <schematicView>
                <p svgId="connector129" layer="schematic" terminalId="connector129terminal"/>
            </schematicView>
            <pcbView>
                <p svgId="connector130" layer="copper1"/>
                <p svgId="connector130" layer="copper0"/>
            </pcbView>
        </views>
    </connector>

where schematic view has a different pin number. I'm wondering if replacedby connector1 will work (or work automatically for all pins) if applied to the schematic connectorId to change it back in to sequence (i.e. make all instances connector1 which is what is desirable!)

    <connector type="female" id="connector130" replacedby="connector1" name="1INa" replacedby="Pin 2">
        <description>Clockwise Input 1</description>
        <views>
            <breadboardView>
                <p svgId="connector130" layer="breadboard"/>
            </breadboardView>
            <schematicView>
                <p svgId="connector129" layer="schematic" terminalId="connector129terminal"/> replacedby="connector1"
            </schematicView>
            <pcbView>
                <p svgId="connector130" layer="copper1"/>
                <p svgId="connector130" layer="copper0"/>
            </pcbView>
        </views>
    </connector>