Improvement/imas 5174

[imbeauf]

---

📚 Documentation preview 📚: https://imas-data-dictionary--240.org.readthedocs.build/en/240/

[github-actions]

Diff of generated Data Dictionary XML file

[maarten-ic]

See below suggestion for improving the generated documentation.

Some things that would be good to discuss tomorrow in the progress meeting:

1. Do we need a CI check to flag any introduced_after_version metadata (to avoid accidentally introducing these in the future)?
2. How do we ensure that this change is applied universally? Github indicates that this PR is out-of-date with the develop branch (see screenshot). We also have another 10 open Pull Requests (and at least some of them add introduced_after_version tags).

[github-actions]

Diff of generated Data Dictionary XML file

[github-actions]

Diff of generated Data Dictionary XML file

[imbeauf]

Thanks @maarten-ic for these comments. I have checked that the PR that was merged since the creation of this one wasn't touching these lifecycle tags.
I have adopted already the metadata change in all PRs I created during the last month (since the decision), but I will review all the ongoing PRs and update them if necessary.
After that, I don't think we need a CI test.

[DavidPCoster]

I would have appreciated a short description of why this change was needed. I don't think it will break any physics code and so have approved the change.

[imbeauf]

I would have appreciated a short description of why this change was needed. I don't think it will break any physics code and so have approved the change.

The reasons for this change are explained here:
https://jira.iter.org/browse/IMAS-5174?filter=-1
The idea is to facilitate the life of the user (introduced_with_version is more practical), not the life of the DD developer (introduced_after_version is more practical).
In addition, all other lifecycle metadata are of type "with_version" instead of "after_version", so it's a way to harmonize with the other metadata

[SimonPinches]

I am happy to approve but this PR will change how we handle releases in the future. At present, we integrate changes into the develop branch which then appear in the next release (and are marked with introduced_after_version). Now, at release (which is the first time when the next release tag is known) we will have to go through all the changes in develop and update the introduced_with_version to point to this (new) release.

[github-actions]

Diff of generated Data Dictionary XML file

[github-actions]

Diff of generated Data Dictionary XML file

[imbeauf]

I am happy to approve but this PR will change how we handle releases in the future. At present, we integrate changes into the develop branch which then appear in the next release (and are marked with introduced_after_version). Now, at release (which is the first time when the next release tag is known) we will have to go through all the changes in develop and update the introduced_with_version to point to this (new) release.

In fact, we know already from the develop branch whether the next tag will be a micro, minor (most cases) or major release. So we can introduce the "introduced_with_version" with each new Pull Request, and in case of later tag change (e.g. micro to minor), we can correct those tags a posteriori.
All other lifecycle tags are already handled like this anyway, so it's not a drastic process change.

[imbeauf]

I have solved the conflicts on this branch, I think it can be merged now.