Fix ambiguous prefixed cubic units

[angularsen]

Motivation

Fixes #1617 and #1645.

Some cubic units used Prefixes where the prefix only applied to the generated unit name, not to the cubed length unit. That made abbreviations such as km³, hm³, and mm³/kg ambiguous or wrong:

• km³/hm³ should mean cubic kilometers/hectometers, not 1000 or 100 cubic meters.
• mm³/kg should mean cubic millimeters per kilogram, not millesimal cubic meters per kilogram.

This follows the SI prefix model where the prefixed unit symbol can itself be raised to a power: https://www.bipm.org/en/measurement-units/si-prefixes

The original intent for the generated cubic foot/meter count units seems to have been real-world count-style volume units such as kcf and Kcm, rather than true cubic-prefixed SI units. This PR keeps those concepts, but gives them explicit names and abbreviations so they do not conflict with true prefixed cubic length units.

For cubic feet, this uses the common gas-volume forms Ccf, Mcf, and MMcf. EIA lists Ccf as 100 cubic feet and Mcf as 1000 cubic feet: https://www.eia.gov/tools/faqs/faq.php?id=45&t=8

For thousand cubic meters, this uses 10³·m³ as the primary abbreviation and keeps kcm/Kcm as aliases. ENERGY STAR Portfolio Manager lists Kcm as thousand cubic meters.

Changes

• Replace SpecificVolumeUnit.MillicubicMeterPerKilogram with SpecificVolumeUnit.CubicMillimeterPerKilogram.
• Remove VolumeUnit.HectocubicMeter; use VolumeUnit.CubicMeter for 100 m³ values.
• Replace VolumeUnit.KilocubicMeter with VolumeUnit.ThousandCubicMeter.
• Replace VolumeUnit.HectocubicFoot, KilocubicFoot, and MegacubicFoot with HundredCubicFoot, ThousandCubicFoot, and MillionCubicFoot.
• Preserve existing enum numeric values for renamed units where the semantic meaning is preserved.
• Keep old non-conflicting generated abbreviations as secondary parsing aliases.
• Add XML docs with source URLs for the explicit replacement units.
• Add regression tests for the ambiguous abbreviations and renamed units.
• Document the prefix-generation rule in the unit definition schema docs.
• Document the v6 breaking changes in the upgrade guide and release tracker.

Migration notes

• hm³ and km³ now mean true cubic hectometers and cubic kilometers.
• mm³/kg now means true cubic millimeters per kilogram.
• For 100 cubic meters, use Volume.FromCubicMeters(100) or convert with VolumeUnit.CubicMeter.
• For count-style cubic meter/foot units, use the new explicit enum names listed above.

Validation

• generate-code.bat
• dotnet test UnitsNet.Tests --filter "FullyQualifiedName~UnitsNet.Tests.VolumeTests|FullyQualifiedName~UnitsNet.Tests.CustomCode.SpecificVolumeTests"

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96%. Comparing base (3b610bc) to head (537b546).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@          Coverage Diff           @@
##           master   #1700   +/-   ##
======================================
  Coverage      96%     96%           
======================================
  Files         457     457           
  Lines       29310   29301    -9     
======================================
- Hits        28247   28239    -8     
+ Misses       1063    1062    -1     

Flag	Coverage Δ
net48	95% <100%> (+<1%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[claude]

Review: Fix ambiguous prefixed cubic units

Reviewed via gh pr diff. Overall this is a well-scoped, well-tested fix for a real correctness bug in prefix generation for cubed units. Nice work tracking down the root cause and adding regression coverage.

Breaking changes

This is correctly a v6-only change (enum renames, abbreviation reassignment, and one silent value fix), and the PR does the right things around it:

• Renames preserve the underlying enum numeric values (HectocubicFoot→HundredCubicFoot = 20, KilocubicFoot→ThousandCubicFoot = 28, KilocubicMeter→ThousandCubicMeter = 29, MegacubicFoot→MillionCubicFoot = 34), so binary/enum-value compatibility for existing serialized values is preserved even though names change.
• VolumeUnit.HectocubicMeter is removed outright (not renamed) since 100 m³ is just CubicMetered values — correct, since keeping a redundant enum member around would be worse than using the existing unit.
• The genuinely silent behavior change is SpecificVolumeUnit.MillicubicMeterPerKilogram → CubicMillimeterPerKilogram: previously mm³/kg parsed with base units Decimeter and a 1e-3 factor (i.e., it silently meant "1/1000 of an m³/kg", not "cubic millimeters"). Old code parsing "4.2 mm³/kg" got a different numeric result than the new code will. This is the one change that's a real value fix, not just a rename — worth calling out even more prominently in the upgrade guide as the change most likely to silently affect existing data (the guide does mention it, good).
• hm³/km³ abbreviations are correctly freed up to mean the existing CubicHectometer/CubicKilometer units (verified CubicHectometer/CubicKilometer already carry those abbreviations in Volume.restext), closing the ambiguity described in Convertion from m³ to hm³ always 0 #1617/Conversion from m³/kg to mm³/kg is wrong #1645.

New units

The three new count-style cubic-foot units (HundredCubicFoot/Ccf, ThousandCubicFoot/Mcf, MillionCubicFoot/MMcf) and ThousandCubicMeter are industry-standard, well-defined (EIA, ENERGY STAR Portfolio Manager, Census Bureau sources cited in XmlDocRemarks), and non-obscure — used in real gas/water utility billing. This satisfies the widely-used/well-defined bar in .agents/criteria-for-adding-quantities-and-units.md. Good use of source links in the XML doc remarks.

One nit: ThousandCubicMeter's primary/default abbreviation is now 10³·m³ (with kcm/Kcm as parse-only aliases). That's an unusual default ToString() output compared to the rest of the unit system, which mostly favors compact conventional symbols. Given Kcm is cited as the real-world convention (ENERGY STAR), consider whether Kcm should be the primary/default abbreviation instead, with 10³·m³ as an alias — unless there was a deliberate reason to prefer the unambiguous power-of-ten notation as the default (worth a sentence in the PR description if so).

Generated code

Spot-checked Volume.g.cs/VolumeUnit.g.cs and SpecificVolume.g.cs/SpecificVolumeUnit.g.cs (both ILinearQuantity-style, not affine/logarithmic, so no IAffineQuantity/ILogarithmicQuantity cases apply here):

• Enum values, GetDefaultMappings(), conversion delegate registration, From* factory methods, and .restext abbreviation resources are all consistently regenerated and match the JSON source — no drift spotted.
• Confirmed the actual bug via the generated diff: the old KilocubicMeter/HectocubicFoot/MegacubicFoot conversion factors (* 1e3d, * 1e2d, * 1e6d) are numerically unchanged after the rename — those really were simple linear multiples, so the rename is safe/behavior-preserving. The old MillicubicMeterPerKilogram factor (* 1e-3d) is genuinely replaced by / 1e9 for the new CubicMillimeterPerKilogram — confirming that one was an actual bug, not just a naming issue.

Note on scope: This PR fixes the JSON definitions for Volume/SpecificVolume only — it doesn't touch CodeGen/Helpers/PrefixBuilder/ itself. The underlying pattern (a Prefixes entry applied to a unit whose abbreviation embeds another unit raised to a power, e.g. m³, m²) could in principle recur in other quantities. The new schema-doc guidance (Docs/quantity-and-unit-definition-schema.md) is a reasonable mitigation, but it's convention-only — nothing in CodeGen would catch a future contributor reintroducing the same bug in, say, a new squared/cubed unit. Not a blocker for this PR, but might be worth a follow-up issue to see if other quantities have similar latent issues, or whether CodeGen could warn when Prefixes is combined with BaseUnits referencing a unit that itself appears with an exponent in the abbreviation.

Test coverage

Good regression tests added:

• ConvertByAbbreviation_CubicMetersToTrueCubicPrefixedUnits (hm³, km³) and ConvertByAbbreviation_CubicMetersPerKilogramToCubicMillimetersPerKilogram directly test the bug being fixed via UnitConverter.TryConvertByAbbreviation, which is exactly the right level (through the abbreviation parser, not just the enum-to-enum conversion).
• Existing generated test-base overrides were mechanically updated to the new names/values — consistent with the JSON changes.

Style/docs

• XmlDocSummary/XmlDocRemarks with source URLs on all four new units is a nice practice for justifying non-obvious count-style units — matches the "well-defined, cite sources" expectation from the contribution criteria.
• Upgrade guide (Docs/upgrading-from-5.x-to-6.x.md) changes are thorough and clearly explain the "why" (km³ should mean (1000 m)³), which will help users migrating.

No security concerns and no performance concerns beyond the existing compiled-delegate conversion approach, which is unaffected here.