Parts policy discussion

[vanepp]

This is a continuation (with a better topic name) from #367 . The intent is to modify and possibly write new standards for parts. We have the part file format document

https://github.com/fritzing/fritzing-app/wiki/2.1-Part-file-format

and the graphics standards

https://fritzing.org/fritzings-graphic-standards

both of which may need updates as part of this discussion, but which provide the basis for this discussion.

@KjellMorgenstern @mMerlin @failiz where suggested in #367 as people who need to be involved, but I expect anyone else that is interested should also be welcome to join in.

My broad outline is to get a parts policy in place that allows automated checking of parts and consistency of parts (at least those included in core parts) so schematic as one instance looks the same and interoperates well with other parts. The longer term goal is, once a policy is in place, to start a project to update the parts in core parts to meet the new standard. (that is likely to be a lot of work, but requires the policy to be in place to allow it!) That would also allow the automated checking of parts that are submitted to core parts to make sure they meet the standards. However it leaves the user able to create custom parts that don't meet the standards (either due to time constraints or lack of need of some views) for their personal use which has been one objection raised in past discussions on this topic. Another topic is the layout of the repository as discussed in #4018 . Documenting the format of the .fzpz file and its association / conversion to the repository format should be done. I am not aware of any documentation on the format of the .fzpz file existing (pointers to anything I have missed are welcome!) Documentation on each field in the fzp file would be useful. For instance the version field is often set to 4 where I think it should start at 1 for a new part and increase by one for each new version of the part. My update to the obsolete.py script available in #347 addresses that by setting the version field to 1 if there isn't one already or increasing the current version field by 1 if there is one.. Issue #365 to standardize the parts labels (which affects the label field in the fzp file) also enters in to this discussion as I think it is desirable to standardize the label field in parts. File name conventions for fzp and svg files are also an issue that needs to come up. I would prefer that the version number appear in the files so for the first version of the part the fzp and svg files end in _1 such as part.fc-51_1.fzp for the first version of a part. One question would be is there a need to add a guid field (a globally unique identifier) to the file name as parts editor currently does when editing parts? As noted I think we need to update the part file format document to specify all the fields in a fzp file along with their suggested initial value and what they relate to in other files. As an example

 <breadboardView>
      <layers image="breadboard/fc-51_breadboard.svg">
        <layer layerId="breadboard"/>
      </layers>
  </breadboardView>

The layerId field here needs to match the group id (in both case and spelling) in the svg file specified in the image file a couple of lines above it. Documenting the special case properties and what they do would be good. An example is all the special formats for a breadboard such as

<module moduleId="Breadboard-test-ModuleID" fritzingVersion="0.12.34">

where the trailing ModuleID in the moduleId field suppresses rotation by 45degrees in a breadboard

<property name="family">Breadboard</property>
    <property name="size">full+ test</property>

the family needs to be Breadboard with the size property selecting between the possibilities (and that the combination of family and size need to be unique!)

<breadboardView>
      <layers image="breadboard/breadboard2.svg">
        <layer layerId="breadboardbreadboard"/>
      </layers>
</breadboardView>

and the breadboard layerId "breadboardbreaddboard" trips special code that allows the part to move down to the same level as the breadboards. This is used by the Arduinos for instance (which are otherwise not a breadboard) I think to allow shields to be mounted above them. That will probably do to start this discussion rolling I hope!

[vanepp]

As a start towards better documentation/standards for part creation I would like to float the idea of a common .fzp file format. Because it is xml it doesn't need a common format, but I think a common format (which automated tools can then enforce) may be useful. So starting from the parts file format document here

https://github.com/fritzing/fritzing-app/wiki/2.1-Part-file-format

these two are clear

fritzing-parts/core # parts in the core parts bin fritzing-parts/obsolete # obsolete parts from core

fritzing-parts/contrib

this one is less clear. It is currently empty. I assume (but don't know for sure) that it was intended for user contributed parts but current practice is to load those in to core. So this may be a candidate for removal?

A currently missing part of this document that I think we should add is the .fzpz file format and how it relates to the folder layout as it currently isn't documented anywhere that I know of and it should be documented somewhere.

part.part_name.fzp loads in to

Documents\Fritzing\parts\user\part_name.fzp

with the svgs (breadboard, icon, schematic and pcb) going in to the associated svg directory i.e.

svg.breadboard.part_name.breadboard.svg

goes in to

Documents\Fritzing\parts\svg\user\breadboard\part_name.breadboard.svg

again there are empty (and apparently unused) contrib directories here which maybe should be removed?

on to FZP format

the current example is

<?xml version='1.0' encoding='UTF-8'?>

but most of the actual fzp files in core are of the form

<?xml version='1.0' encoding='UTF-8' standalone='no'?>

I don't know what standalone='no' does or if it is worth making it the standard or not. Opinions? Then there is the next line, currently

but a more common in core parts version has the parts editor added "referenceFile" as well. I believe it is only added by parts editor and not actually used for anything except reference to where the part was cloned from, so the question becomes do we want to keep it and if so require it or leave it as an option. as well I think some advise should be added here of the nature that the moduleId must be unique in the repository (and in Fritzing itself) and thus the guid fields in these two examples. Past practice in core parts was to strip the guid field (and presumably verify that there were no dups once that was done!) so the question becomes do we want to keep doing that or require a guid in moduleIds. I would favor the remove guid option, as insuring uniqueness in core parts should be easily automatable and it makes the file names easier to copy if you can't use a copy/paste for some reason (and easier even with copy/paste!) Stefan Hermann I would add the advise if you are making a change to a part you should add something like this to the author field Stefan Hermann (modified by vanepp Apr 2023) to document who and when made the last modification.