SemVer major-zero behavior for `nova bump`

[stiwicourage]

Plan: SemVer major-zero behavior for nova bump

Goal

Change nova bump / Update-NovaModuleVersion so automatic bumping does not move from 0.y.z to 1.0.0.

When the current version is in the SemVer initial development range (0.y.z):

• Patch stays Patch
• Minor stays Minor
• Major is downgraded to a Minor bump for version calculation
• the user gets a clear message that:
  • major version zero is for initial development
  • anything may change at any time
  • once the software is stable, the version should be set manually to 1.0.0
  • after that, nova bump can increment the major version as normal

-Preview must continue to work exactly as it does today.

---

Expected behavior

Stable bumps while current version is 0.y.z

Current version	Detected label	Planned version	Notes
0.0.1	Patch	0.0.2	Normal patch behavior
0.0.1	Minor	0.1.0	Normal minor behavior
0.1.0	Major	0.2.0	Major is remapped to minor during initial development
0.2.0	Minor	0.3.0	Normal minor behavior

Required message for major-zero guidance

Show guidance when a Major label is detected while the current major version is 0 and the command is not using -Preview.

The message should explain:

1. 0.y.z is initial development
2. breaking changes do not automatically promote the project to 1.0.0
3. users should manually set the version to 1.0.0 once the software is stable
4. after 1.0.0, nova bump will resume normal major increments

Preview mode

Do not change preview behavior.

Examples that must remain valid:

• 0.0.1-rc1 + Major + -Preview -> 0.0.1-rc2
• existing prerelease stems still increment on the same semantic core
• --preview --what-if output format must stay intact

---

Implementation approach

1. Normalize the effective bump label for stable major-zero workflows

Primary change point:

• src/private/release/GetNovaVersionUpdateWorkflowContext.ps1

Add a small helper that:

• inspects the current version from Get-NovaProjectInfo
• checks whether:
  • current major is 0
  • detected label is Major
  • -Preview is not active
• returns an effective label of Minor for version calculation
• preserves the original detected label so the result can still explain why the bump was remapped

Recommended shape:

• keep the current public flow intact
• introduce a small helper such as:
  • Get-NovaEffectiveVersionLabel
  • or Resolve-NovaVersionLabelForInitialDevelopment

The workflow context should then carry both:

• Label = original detected label (Major)
• EffectiveLabel = actual applied label (Minor when current version is 0.y.z and not preview)

This keeps intent visible while avoiding hidden behavior.

2. Use the effective label for version calculation

Likely file:

• src/private/release/GetNovaVersionUpdateWorkflowContext.ps1

Pass the effective label into:

• Get-NovaVersionUpdatePlan

Do not change the core prerelease logic unless strictly necessary. The current prerelease behavior already routes through:

• src/private/release/GetNovaVersionUpdatePlan.ps1
• src/private/release/GetNovaVersionPartForLabel.ps1
• prerelease label helpers

That logic should remain untouched unless a failing test proves a targeted fix is required.

3. Add a single explicit advisory message

Preferred output point:

• src/public/UpdateNovaModuleVersion.ps1

Reason:

• this keeps internal version math quiet
• it makes the guidance visible on the public cmdlet and routed CLI output
• it avoids scattering message logic across private helpers

Suggested condition:

• result/workflow says original label was Major
• effective label used was Minor
• current version major was 0
• -Preview was not used

Suggested message content:

Major version zero (0.y.z) is for initial development, and anything MAY change at any time. Nova did not automatically promote this project to 1.0.0. Once your software is stable, set the version to 1.0.0 manually. After that, nova bump will increment major versions normally.

Keep the existing preview summary output intact.

4. Preserve CLI summary compatibility

The standalone CLI currently formats version plans in the CLI layer. Keep that output shape stable, but update the version target for major-zero cases.

For the examples in this feature request, the expected plans should become:

• Version plan: 0.0.1 -> 0.0.2 | Label: Patch | Commits: 32
• Version plan: 0.0.1 -> 0.1.0 | Label: Minor | Commits: 33
• Version plan: 0.1.0 -> 0.2.0 | Label: Major | Commits: 34

Note that the displayed Label can remain Major if the implementation also surfaces the advisory, because the detected change type is still major even though the applied bump is minor during 0.y.z.

If that feels ambiguous in practice, a follow-up option is to show both values, for example Label: Major (applied as Minor during 0.y.z), but that is a product wording decision and should only be added if tests and docs are updated together.

---

Test plan

Unit and internal coverage

Update:

• tests/CoverageGaps.ReleaseInternals.Tests.ps1
• tests/NovaCommandModel.BumpAndCli.Tests.ps1

Add coverage for:

1. 0.0.1 + Patch -> 0.0.2
2. 0.0.1 + Minor -> 0.1.0
3. 0.1.0 + Major -> 0.2.0
4. 0.2.0 + Major -> 0.3.0
5. 1.2.3 + Major -> 2.0.0 remains unchanged
6. 0.0.1-rc1 + Major + -Preview -> 0.0.1-rc2 remains unchanged
7. advisory message appears only for stable 0.y.z major-label cases
8. advisory message does not appear for:
   • patch bumps
   • minor bumps
   • preview bumps
   • stable releases where current major is 1 or greater

CLI integration coverage

Update:

• tests/NovaCommandModel.StandaloneCli.Tests.ps1

Add or update CLI tests for:

1. nova bump --what-if on 0.0.1 with patch history
2. nova bump --what-if on 0.0.1 with feature history
3. nova bump --what-if on 0.1.0 with breaking-change history
4. confirmation that CLI output still includes the normal version-plan line
5. confirmation that --preview --what-if output stays unchanged

Regression coverage

Re-run the existing bump/release tests that already cover:

• prerelease finalization
• existing preview stem incrementing
• CI fallback when no commits exist after the latest tag
• public cmdlet output and routed CLI output

---

Documentation plan

Update these user-facing docs together with the feature:

• src/resources/cli/help/bump.psd1
• docs/versioning-and-updates.html
• docs/commands.html
• docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md if present/generated in the normal help flow
• README.md if contributor guidance mentions bump semantics or examples that would now be misleading
• CHANGELOG.md

Documentation points to add

1. 0.y.z is treated as initial development
2. breaking changes during 0.y.z do not auto-promote to 1.0.0
3. Nova only auto-bumps patch and minor while major is zero
4. users should manually choose 1.0.0 once the API/software is stable
5. after 1.0.0, major bumps work normally again
6. -Preview behavior is unchanged

Example text to document

0.0.1 + Patch -> 0.0.2
0.0.1 + Minor -> 0.1.0
0.1.0 + Major -> 0.2.0
1.4.0 + Major -> 2.0.0
0.0.1-rc1 + Major + -Preview -> 0.0.1-rc2

Changelog placement

Add the final feature wording under:

• ## [Unreleased]
• ### Added or ### Changed

Recommended wording should describe the final user-facing behavior, not the internal implementation.

---

Acceptance criteria

The feature is complete when all of the following are true:

• Update-NovaModuleVersion never auto-promotes 0.y.z to 1.0.0
• a detected Major bump on 0.y.z produces the next 0.(y+1).0
• patch and minor behavior under 0.y.z stay correct
• -Preview behavior remains unchanged
• CLI version-plan output still works
• users see a clear advisory about SemVer major zero and manual 1.0.0
• docs and help reflect the new rule
• tests cover stable, preview, CLI, and regression scenarios

---

Suggested implementation order

1. Add the effective-label helper and workflow context fields.
2. Update the public result/output path with the advisory message.
3. Add unit tests for 0.y.z patch/minor/major behavior.
4. Add CLI integration tests for nova bump --what-if output.
5. Update help, docs, README review, and changelog.
6. Run the targeted test suite plus the existing bump/release regression tests.

---

Open product decision

Decide whether the displayed Label in the version-plan output should remain:

• Major (detected intent), or
• Minor (applied result), or
• Major (applied as Minor during 0.y.z)

My recommendation: keep Label as Major, add the advisory message, and keep the actual target version as the source of truth. That preserves commit classification while still making the SemVer major-zero rule explicit.