Start versioning for pyaml and tango-pyaml

[gupichon]

🧩 Context

Both projects are still under active development.
To improve traceability, communication, and integration between repositories, it would be valuable to introduce a formal versioning scheme starting now.

---

🎯 Goal

• Start with version 0.1.0.
• Follow a SemVer-inspired scheme adapted to the pre-1.0 phase (0.y.z):
  • Y (MINOR) → incremented for breaking changes and for major new additions preparing for v1.0.0.
  • Z (PATCH) → incremented for backward-compatible improvements (bug fixes, optional parameters, internal refactors).
• Revisit the strategy before reaching v1.0.0, once the public API and YAML formats are stable.

---

📘 Proposed versioning policy (0.y phase)

• Initial release: 0.1.0

• Rules:

  • Increment MINOR (y) when:
    • A public API changes (signature, behavior, naming).
    • YAML schema or configuration interface evolves incompatibly.
    • A major new feature or subsystem is introduced (e.g., a new model type, control backend, or configuration layer).
  • Increment PATCH (z) for:
    • Backward-compatible fixes,
    • Internal improvements,
    • Optional arguments or non-breaking enhancements.

• Communication:

  • Update the CHANGELOG primarily for notable updates (major features or breaking changes).
  • Smaller or internal-only updates can be summarized later before a release.

Examples

From	To	Type	Example
0.1.0	0.2.0	MINOR	Added a new subsystem or refactored magnet model interface
0.2.0	0.2.1	PATCH	Fixed a bug or improved logging
0.3.0	0.4.0	MINOR	Introduced a new configuration parser module

---

🔗 Coordination between pyaml and tango-pyaml

• Compatibility declaration:
  In tango-pyaml, declare supported pyaml versions (e.g., pyaml>=0.2,<0.4).
• Version alignment:
  Both projects can evolve independently, but each tango-pyaml release should clearly indicate which pyaml versions it supports.
• Cross-CI testing:
  Test multiple pyaml versions in tango-pyaml’s CI matrix to ensure compatibility.

---

🚀 Release process proposal

1. Stabilize the branch and update the CHANGELOG.md (at least for key or major changes).
2. Discuss the version bump (MINOR/PATCH) as part of the Merge Request (MR) review.
3. Tag the release (v0.y.z).
4. CI builds, tests, and publishes the release (PyPI or internal registry).
5. Announce the release with concise GitHub Release notes and link to the changelog.
6. Indicate the compatible pyaml/tango-pyaml range in documentation.

Example CHANGELOG excerpt

## [0.3.0] - 2025-10-21
### Breaking changes
- Refactored model structure; see migration guide for details.

### Added
- Introduced `linear_cfm_model` with enhanced calibration logic.
- Added support for YAML schema v0.4.

### Fixed
- Improved error handling when loading configuration files.

---

⚙️ Technical integration (Hatch / Python)

• Version source:
  pyaml/__init__.py

  __version__ = "0.1.0"

• Dynamic versioning:
  Already configured via

  [tool.hatch.version]
  path = "pyaml/__init__.py"

• Action items:

  • Initialize __version__ = "0.1.0" in both pyaml and tango-pyaml.
  • Add a CHANGELOG.md (updated mainly for major updates).
  • Ensure version bumps are discussed and validated during MR reviews.

---

❓ Open questions

• Should both projects start at the same version (0.1.0)?
• Do we adopt the rule MINOR = breaking or major addition / PATCH = non-breaking for the full 0.y phase?
• Where should this policy be documented (README, CONTRIBUTING, or a dedicated file)?
• Define the compatibility window between tango-pyaml and pyaml (e.g., N and N−1 MINOR versions)?
• What criteria will define readiness for 1.0.0 (API maturity, documentation, real-world adoption, etc.)?

[JeanLucPons]

Thanks for the proposal it is nice and we indeed have to start soon with a versioning scheme.
This policy could fit in the CONTRIBUTING file.
However it might be a bit early to start with, the projects are still in specification/first draft state.

[gubaidulinvadim]

@JeanLucPons, we actually need some kind of versioning for pyaml and tango-pyaml right now. There are some issues with updating it on a digital twin without versioning that @gupichon have encountered. Otherwise, the tests at SOLEIL and SOLEIL II digital twin will get delayed.

[JeanLucPons]

We are currently discussing the issue you get with Guillaume. It would be nice that you share your config and the way you are using it. It seems that the issue is related to CFM and it is strange that it works as it is today.

[gubaidulinvadim]

For me, it's a good and necessary suggestion. For MR version bumps, we could say that for MR with only minor updates (minor version bump) we should always squash commits to the main branch into one merge commit. So the version will not go up from 0.1.0 to 0.1.45 after a single MR.