You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Migrate GitHub wiki content to Docs/ folder (#1659)
Consolidate 16 wiki pages into Docs/ as the single source of truth,
deduplicating content previously split across the wiki, CONTRIBUTING.md,
and .claude/.
The motivation is to make docs easier to maintain with AI agents.
The key benefit of wiki is to more easily accept contributions and
automatic menu navigation per page, but contributions have historically
been zero and AI makes it much more efficient to manage docs.
The idea is to preserve wiki pages for a while, but link replace their
content with links to these files instead.
New Docs/ structure:
- adding-a-new-unit.md, adding-operator-overloads.md, precision.md
- string-formatting.md, serialization.md, saving-to-database.md
- extending-with-custom-units.md, experimental-generic-math.md,
nanoframework.md
- upgrading-from-{3,4,5}.x-to-{4,5,6}.x.md
-
collaborators/{issues-and-pull-requests,releasing-nugets,regenerate-nuget-api-key}.md
- README.md (index)
Other changes:
- Fix backwards convention in conversion functions: prefer * for
FromUnitToBaseFunc and / for FromBaseToUnitFunc (wiki had it reversed).
- Merge two overlapping NuGet release wiki pages into
releasing-nugets.md.
- Skip Changelog wiki page (GitHub Releases is canonical) and Home
(placeholder).
- CONTRIBUTING.md: slim down, link to Docs/ for detailed
conversion/abbreviation rules.
- CLAUDE.md: add Documentation section linking to Docs/, reference
adding-a-new-unit.md for conversion guidelines.
- .claude/criteria-for-adding-quantities-and-units.md: reference Docs/
instead of wiki.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
**[Adding a New Quantity or Unit](Docs/adding-a-new-unit.md)**
10
10
11
11
We also want the person with the idea, suggestion or bug report to implement the change in code and get a sense of ownership for that piece of the library.
12
12
This is to help grow the number of people that can contribute to the project and after someone new lands that first PR we often see more PRs from that person later.
@@ -24,19 +24,11 @@ This is to help grow the number of people that can contribute to the project and
24
24
* Test method: `<method>_<condition>_<result>` (`Parse_AmbiguousUnits_ThrowsException`)
25
25
* If there are many tests for a single method, you can wrap those in an inner class named the same as the method and then you can skip that part of the test method names
26
26
27
-
## Unit definitions (.JSON)
27
+
## Unit Definitions (.JSON)
28
28
29
29
For a fairly complete summary of the unit definition JSON schema, see [Meter of Length](https://github.com/angularsen/UnitsNet/blob/master/Common/UnitDefinitions/Length.json). It has prefix units and multiple cultures.
30
30
31
-
### Conversion functions
32
-
33
-
Converting from unit A to B is achieved by first converting from unit A to the base unit, then from the base unit to unit B. To achieve this, each unit defines two conversion functions.
34
-
35
-
* Prefer multiplication for `FromUnitToBaseFunc` (`{x} * 2.54e-2` for `Inch` to `Meter`)
36
-
* Prefer division for `FromBaseToUnitFunc` (`{x} / 2.54e-2` for `Meter` to `Inch`)
37
-
* Prefer scientific notation `1e3` and `1e-5` instead of `1000` and `0.00001`
38
-
* Prefer a constant if the conversion factor is finite (`{x} * 2.54e-2` for `Inch`)
39
-
* Prefer a calculation if the conversion factor is infinite (`({x} / 72.27)*2.54e-2` for `PrinterPoint`)
31
+
For detailed conventions on conversion functions, abbreviations, base dimensions, and more, see [Adding a New Unit](Docs/adding-a-new-unit.md#1-add-or-modify-json-file-for-a-quantity-class).
40
32
41
33
### Units
42
34
@@ -46,17 +38,10 @@ Generally we try to name the units as what is the most widely used.
46
38
47
39
**Note:** We should really consider switching variant prefix to suffix, since that plays better with kilo, mega etc.. Currently we have units named `KilousGallon` and `KiloimperialGallon`, these would be better named `KilogallonUs` and `KilogallonImperial`.
48
40
49
-
### Unit abbreviations
50
-
51
-
A unit can have multiple abbreviations per culture/language, the first one is used by `ToString()` while all of them are used by `Parse()`.
41
+
## More Documentation
52
42
53
-
* Prefer the most widely used abbreviation in the domain, but try to adapt to our conventions
54
-
* Add other popular variants to be able to parse those too, but take care to avoid abbreviation conflicts of units of the same quantity
55
-
* Use superscript (`cm²`, `m³`) instead of `cm^2`, `m^3`
56
-
* Use `∆` for delta (not `▲`)
57
-
* Use `·` for products (`N·m` instead of `Nm`, `N*m` or `N.m`)
58
-
* Prefer `/` over `⁻¹`, such as `km/h` and `J/(mol·K)`
59
-
* Use `h` for hours, `min` for minutes and `s` for seconds (`m` is ambiguous with meters)
60
-
* Use suffixes to distinguish variants of similar units, such as `gal (U.S.)` vs `gal (imp.)` for gallons
61
-
*`(U.S.)` for United States
62
-
*`(imp.)` for imperial / British units
43
+
See [Docs/](Docs/README.md) for the full documentation index, including:
44
+
-[Precision](Docs/precision.md) — conversion precision and test guidelines
0 commit comments