gEDA-user: âsymversionâ documentation update

[Colin D Bennett <colin@xxxxxxxxxxx>]

The âsymversionâ attribute's documentation says that this attribute
should not be placed on new symbols, but only (1) on symbols âaccepted
into the main gEDA symbol libraryâ, and even then (2) only when a
change is made to the symbol.

I always add symversion=1.0 to my custom symbols because (1) it makes
updating the version easier when the first change is made (so it is more
likely to be done), and
(2) version control system diffs show the version number change more
readily and consistent with subsequent version updates when it's
only a text change (e.g., â1.0â -> â1.1â) rather than an entirely new
attribute after the first change.

Anyway, what is the harm in adding symversion to brand new symbols?
The wiki page says âNew symbols should not receive this attribute at
all. Only when the symbol is change should this attribute be placed
into the symbol file and maintained.â

It seems like the wiki has many unnecessary and unexplained mandates
like this. (In the future, let's remember to explain _why_ any such
restriction is necessary or desirable...)

From the geda master attributes list wiki page:

> symversion
> 
> The symversion= attribute is used to version the contents of symbols.
> Normally this attribute is not present, but once a symbol has been
> accepted into the main gEDA symbol library and there are changes to
> it, this attribute must be placed into the symbol file and properly
> incremented. The value of this attribute takes the following form:
> major.minor
> 
> where major and minor are just plain integers (separated by a
> period). The major number is incremented when a symbol has some sort
> of a change which will break or might break an existing schematic.
> The minor number is only incremented when a cosmetic or very minor
> change is made to the symbol. The major and minor numbers are not
> coupled in any way, however, when making major version changes, the
> minor version number can be reset to zero. If this attribute is
> inside of a symbol and that symbol is placed onto a schematic, then
> the symversion= attribute will be automatically promoted and attached
> to the outside of the symbol. During the load of the symbol from
> disk, the value of the symversion= inside the symbol file (if any)
> and the symversion= attached to the symbol (if any) are compared. If
> the values are the same then the placed symbol matches the disk
> symbol file, however if the values do not match, then libgeda will
> output a warning/error message (based on whether it is a major or
> minor version change). New symbols should not receive this attribute
> at all. Only when the symbol is change should this attribute be
> placed into the symbol file and maintained. Users should not attach
> this attribute manually to instantiated symbols. This attribute
> should normally be made invisible when placed inside of a symbol
> file. This attribute is always promoted when it is found inside of a
> symbol (during component placement). Examples: symversion=1.1


How about replacing the symversion section with the following, updated
text:

--------------------------------------- 
The symversion= attribute is used to version the contents of symbols.
Because symbols are, by default, referenced from the schematic and not
embedded within it, problems can occur in a schematic using a
particular symbol if that symbol file is modified.  For instance, if
pins are moved in the symbol, the schematic net lines will no longer
connect to the correct pins.  The symversion= attribute allows
tracking such breaking changes to symbols and notifying the user of
potential problems when a schematic is loaded.

This attribute is optional, but if present it must take the following
form:

major.minor

where major and minor are integers.  The major number is incremented
when a change is made to a symbol that might break an existing
schematic using the prior version of symbol when the new version is
introduced.  The minor number is only incremented when a minor change
is made (a change that cannot break an existing schematic, such as
cosmetic changes while retaining structure such as location of the
pins).

If this attribute is inside a symbol and that symbol is placed onto a
schematic, the symversion= attribute will be automatically âpromotedâ,
causing a copy of the symversion=M.N attribute to be stored on the
symbol instance in the schematic itself.  When a symbol is loaded from
disk, the value of the symversion= inside the symbol file (if any) and
the symversion value attached to the symbol instance on the schematic
are compared.  If the values differ, then libgeda will output a warning
message (for minor version changes) or an error message (for major
version changes).

This attribute should normally be made invisible when placed inside a
symbol file.  This attribute is always promoted when it is found inside
a symbol during component placement.  Users should not attach this
attribute manually to instantiated symbols in a schematic.

Examples:  symversion=1.1  symversion=2.0
--------------------------------------- 


Regards,
Colin


_______________________________________________
geda-user mailing list
geda-user@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user