dotnet / dotnet/Nerdbank.GitVersioning

Establish backward compatible way to innovate on computing version height

Open
#1,482 2 comments 0 reactions 0 assignees View on GitHub
discussion needed enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.