dotnet / dotnet/Nerdbank.GitVersioning
Establish backward compatible way to innovate on computing version height
- Dominant language
- C#
- Stars
- 1.6k
- Forks
- 185
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 46
Description
Changing counting behavior for _existing_ version.json files is a version height breaking change and must either be part of a major version bump of the library or perhaps a new pattern can emerge.
We already have a `versionHeightOffsetAppliesTo` property that is useful to delaying a version height offset to exactly the moment when the version changes in a height-resetting way.
What if we do something similar for a "version height algorithm version"? NB.GV would increment an integer each time it makes a breaking change to how version height is computed, with `1` being the current behavior as of v3.9. `version.json` can opt into a later algorithm version, and can express a desire to opt into a still newer algorithm as of when version.json bumps its declared version again. Something like this:
```json
{
"version": "1.2",
"versionHeightAlgorithmRevision": 2
}
```
and to "schedule" jumping to 3 at the soonest non-breaking opportunity, this could be changed by the user to:
```json
{
"version": "1.2",
"versionHeightAlgorithmRevision": [
{ "appliesTo": "1.2", "revision": 2 },
3,
]
}
```
Or something like that.
Contributor guide
Research direction
Start by locating version.json parsing and the existing versionHeightOffsetAppliesTo behavior. Review how version height is currently computed, then clarify the proposed algorithm-revision model and its compatibility rules. Done means the behavior and upgrade path are specified well enough to implement and test without changing existing version.json results unexpectedly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- build-system, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100