Skip to content

docs: add units policy page #725

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rkratky wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add units policy page #725

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/how-ubuntu-is-made/concepts/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ deb-3-patch-file-headers
debian-policy
debian-directory
debian-maintainer
units-policy
```

## System design
Expand Down
36 changes: 36 additions & 0 deletions docs/how-ubuntu-is-made/concepts/units-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
(units-policy)=
# Units policy

This policy defines how units (file sizes, memory sizes, data transfer rates) should be displayed in Ubuntu software.

## Rationale

There are two ways to represent large quantities:

* **Decimal (base-10):** multiples of 1000, using [SI prefixes](https://en.wikipedia.org/wiki/Metric_prefix) (KB, MB, GB, ...).
* **Binary (base-2):** multiples of 1024, using [IEC prefixes](https://en.wikipedia.org/wiki/Binary_prefix) (KiB, MiB, GiB, ...).

Historically, many applications used SI prefix names while dividing by 1024, creating ambiguity. A "KB" could mean 1000 bytes or 1024 bytes depending on the application. This policy resolves that ambiguity.

## Recommendation

* Use **IEC binary prefixes** (KiB, MiB, GiB, TiB, ...) for quantities that are naturally measured in powers of two (file sizes, memory sizes).
* Use **SI decimal prefixes** (KB, MB, GB, TB, ...) for quantities that are naturally measured in powers of ten (disk capacities, network speeds, clock rates).
* When in doubt, default to **base-2 with IEC prefixes** for file and memory sizes.

## Packaging

When packaging software, the maintainer must ensure the software reports units in accordance with this policy. If upstream software uses SI prefix names for binary quantities, it should be patched to use IEC prefixes instead.

## Exceptions

Command-line tools are exempt from this policy when they:

* Are command-line tools whose output is often parsed by machine (for example, in scripts).
* Display only the prefix without the unit (for example, `M` instead of `MB`).

## See also

* [SI prefixes (Wikipedia)](https://en.wikipedia.org/wiki/Metric_prefix)
* [Binary prefixes (Wikipedia)](https://en.wikipedia.org/wiki/Binary_prefix)
* [ISO/IEC 80000](https://en.wikipedia.org/wiki/ISO/IEC_80000)
Loading