[PROPOSAL] better pysimCoder versions and diagram version fixups

[zdebanos]

@robertobucher @ppisa @michallenc

I am creating this issue to address the ways of pysimCoder versioning. Currently, the version is specified in the const.py file and since 2022 it has consistently been 0.95.

The reason I am bringing this up is that in future, one may have a diagram created in the older version of pysimcoder and in new versions, the diagram must be automatically changed to match with the new version of pysimcoder.

I am tagging you because I would like to hear your opinions on this. This issue raises several questions

• How to specify the version? In a file or something else?
• When should the version be changed? With each commit or each month?
• If any changes are made to the diagram handling, a set of rules must be defined to transform the old diagram to a newer one.

I think that @michallenc 's change to RcpBlk generalizes the blocks very well and should serve as a baseline for future upgrades. Anything before the RcpBlk change should be considered outdated.

[michallenc]

How to specify the version? In a file or something else?

I would vote for a top level file, ideally a changelog https://keepachangelog.com/en/1.1.0/ + github tag for every release. We can also put the version to supsisim library inside pyproject.toml, but that should apply just to the library I think, not to the entire pysimCoder.

When should the version be changed? With each commit or each month?

I am not sure what is the most common for Python projects, but generally I don't like automatic versioning with each commit. It just makes versioning useless in my opinion, because your version is just an incremented number without any meaning.

I think https://semver.org/spec/v2.0.0.html is quite good for these kinds of projects. We can write changes to the changelog and make new release once we have enough changes (or some big breaking change). The advantage of having a changelog is we can quite easily parse the current version from it. I would start with 0.x.x versioning now so we don't tight us up with a non-breaking API rule. We should of course try to do our changes in a way it doesn't break the compatibility, even in 0.x.x.

I am not sure about periodic releases, pysimCoder is not big enough for that. We can have several big changes or even no contribution at all in one month span.

If any changes are made to the diagram handling, a set of rules must be defined to transform the old diagram to a newer one.

We can store the version inside the diagram, but I am not sure if we will be able to always transform it so new pysimCoder will support it. But with semantic versioning, we could make a rule that diagram interfaces don't change between major versions (API compatibility) and provide backwards compatibility for some number of major versions, while marking those as deprecated and ultimately removing the old support after some time. This would provide the users enough time to update their diagrams. Maybe for small changes there can be automatic update, but I am not sure we can always guarantee that, therefore the major version change rule and backward compatibility.

[zdebanos]

I agree that from the perspective of semantic versioning, every minor should by definition NOT break the diagram. I think that in the top level file so called "diagram milestones" should be specified to mark the major versions where the diagram format/handling is changed.

It makes sense that the diagram must, in most cases, be upgraded manually. But some rules could be specified to simplify the transformation, if it makes sense. Ideally, a user should be notified of such thing.

[robertobucher]

Version is defined in the const.py file AND in the pyproject.toml file (sorry, at present are not on the same version. It is quite simple to integrate the version as new field in the .dgm file.
Major numbers should be only present if there are consistent modifications in the structure of pysimCoder (for example by new features), minor version for bugs.