What is the version of a .pdsc

[slhultgren]

Perhaps pedantic/stupid question.

But what is the version of a .pdsc?

The <release> element in the specification https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/element_releases.html#element_release mentions this: The latest release version is always listed on top.

With the example:

<releases>
  <release version="1.1.1" date="2020-05-12">Fixed a problem with the feature xyz.
  </release>
  <release version="1.1.0" date="2020-03-13">Introduces a new feature xyz.
  </release>
  <release version="1.0.0" date="2020-02-23">First published version.
  </release>
</releases>

In this situation the .pdsc would be recognized as a version 1.1.1.

However, let's imagine a slightly different scenario, where the latest release is not the highest version, for example something like this:

<releases>
  <release version="1.0.1" date="2020-05-12">Fixed a problem.
  </release>
  <release version="1.1.0" date="2020-03-13">Introduces a new feature xyz.
  </release>
  <release version="1.0.0" date="2020-02-23">First published version.
  </release>
</releases>

Here, there was a 1.0.1 bugfix released after the 1.1.0. The tools will however still consider such a .pdsc to be version 1.1.0, not 1.0.1, due to a "highest-version selection" here https://github.com/Open-CMSIS-Pack/devtools/blob/06634cd53ec3e8fdc1f5dffaffa1a9e3a780c25f/libs/rtemodel/src/RtePackage.cpp#L45

This means that from the csolution point of view, the version of a .pdsc is always the highest version of the <release> section, which is not necessarily the newest one or the top one.

I realize that this is perhaps a strange edge-case, but in the above case, it would be necessary to clean the release-notes to this:

<releases>
  <release version="1.0.1" date="2020-05-12">Fixed a problem.
  </release>
  <release version="1.0.0" date="2020-02-23">First published version.
  </release>
</releases>

for the .pdsc to be correctly recognized as a 1.0.1.

This is not a big problem, but perhaps the .pdsc specification documentation for the element should be clarified to : Contains brief information of the main changes in each release version of a Pack. The content is a string written between the opening and closing release tags. The latest release version is always listed on top. The highest version in the release history is regarded as the version of the .pdsc

[jkrech]

The ordering of versions in the <releases> section is about the version attribute and not about the release date. Adding version 1.0.1 after 1.1.0 got already released is actually a bit more complicated:

<releases>
  <release version="1.0.1" date="2020-05-12">Fixed a problem.
  </release>
  <release version="1.1.0" date="2020-03-13">Introduces a new feature xyz.
  </release>
  <release version="1.0.0" date="2020-02-23">First published version.
  </release>
</releases>

You need to take pack version 1.0.0 do that patch and release a pack version 1.0.1. In the pdsc inside of that pack you must not mention version 1.1.0 and have 1.0.1 at the top.

You then need to take version 1.1.0 and create at least a patch 1.1.1 where you add the 1.0.1 to the release history again in the strict version order. This 1.1.1 pdsc file will become that latest pdsc being referenced in the index.pidx and will show

<releases>
  <release version="1.1.1" date="2020-05-12">Adding version 1.0.1
  </release>
  <release version="1.1.0" date="2020-03-13">Introduces a new feature xyz.
  </release>
  <release version="1.0.1" date="2020-05-12">Fixed a problem.
  </release>
  <release version="1.0.0" date="2020-02-23">First published version.
  </release>
</releases>

Please note that packchk will issue an Error:

*** ERROR M396: Vendor.PackName.pdsc (Line 11)
  Release Version not consecutive (newest first): '1.0.1', '2023-12-12' (prev.: '1.0.0', '2024-04-22', see Line 9)

[Torbjorn-Svensson]

@jkrech If there is a strict requirement that the release-nodes should be ordered, why is then the implementation ordering them again? Feels like these two parts is overlapping in a non-intuitive way.

• If it's supposed to be a strict requirement on the order of the nodes in the pdsc file, then the implementation should simply take the first node and do no ordering internally.
• If the implementation is supposed to order the nodes, then the requirement should be loosened to instead be a suggestion/recommendation.

By having both, it's ambiguous, by just viewing the .pdsc file, what version it is really considered to be.

Generally speaking, the specification should be clear what is the considered version and the implementation should be aligned with that. Right now, the implementation in the RtePackage class is not aligned with the, although vague, specification of the PDSC format.