unitsml 0.4.7 → 0.5.1

data/unitsdb/README.adoc

@@ -0,0 +1,1071 @@
+= UnitsDB
+
+== Purpose
+
+This data repository is used in conjunction with UnitsML.
+
+Sources include:
+
+* https://www.bipm.org/en/publications/si-brochure/[BIPM SI Brochure]
+* https://www.nist.gov/pml/special-publication-811[NIST SP 811]
+* ISO 80000 series
+* (in some cases, "Encyclopaedia of Scientific Units, Weights and Measures, Their SI Equivalences and Origins" by François Cardarelli, is consulted)
+
+NOTE: Conversion factors here are not updated with the revised SI.
+
+== Structure
+
+This repository contains the following YAML files:
+
+`dimensions.yaml`:: Contains the base dimensions and their symbols.
+
+`prefixes.yaml`:: Contains the SI prefixes and their symbols.
+
+`scales.yaml`:: Contains the measurement scale types and their properties.
+
+`units.yaml`:: Contains the units and their symbols, with English and French
+names. French translations come from BIPM.
+
+`unit_systems.yaml`:: Contains the unit systems and their symbols.
+
+`quantities.yaml`:: Contains the quantities and their symbols, with English and
+French names. French translations come from BIPM.
+
+
+== Supported languages
+
+The database currently supports the following languages:
+
+* English (en): Primary language for all entries
+
+* French (fr): Provided for units and quantities, sourced from the BIPM SI
+Digital Framework
+
+
+== Versioning
+
+=== Version scheme
+
+UnitsDB follows semantic versioning (https://semver.org/[SemVer]) using a
+`MAJOR.MINOR.PATCH` structure.
+
+Where,
+
+`MAJOR`:: Incremented for incompatible changes that may require updates to consuming applications
+
+`MINOR`:: Incremented for backwards-compatible additions or changes
+
+`PATCH`:: Incremented for backwards-compatible bug fixes
+
+
+=== Version field
+
+Each YAML file in the database contains a `schema_version` field (string) at the
+top level.
+
+[source,yaml]
+----
+schema_version: "2.0.0"
+dimensions:
+  # content follows
+----
+
+The version number is consistent across all files in a given release, ensuring
+the database is treated as a cohesive unit.
+
+=== Version changes
+
+[cols="1,3a"]
+|===
+|Version level |Types of changes
+
+|`MAJOR`
+|
+* Structural changes to the data model
+* Removal of units, dimensions, or quantities
+* Changes to identifier schemes
+* Any other backwards-incompatible changes
+
+|`MINOR`
+|
+* Addition of new units, dimensions, or quantities
+* Addition of new properties to existing entities
+* Other backwards-compatible enhancements
+
+|`PATCH`
+|
+* Corrections to symbols, names, or other properties
+* Fixes to references between entities
+* Other backwards-compatible fixes
+
+|===
+
+=== Version usage
+
+Applications consuming UnitsDB should:
+
+. Check the `schema_version` field to ensure compatibility, ensure all files are
+  consistent with the same version
+. Handle version transitions appropriately based on the semantic versioning rules
+. Document which version(s) of UnitsDB they support
+
+== Content classes
+
+=== Basic structures
+
+==== General
+
+Several shared content models are used across the different entities.
+
+==== Identifier
+
+The Identifier object represents a unique identifier within the identifier type.
+
+Every entity in the database includes an `identifiers` array that contains one or
+more identifiers.
+
+Each identifier has:
+
+`id`:: A unique string that identifies the entity
+`type`:: The system or authority that defines the identifier
+
+The `type: unitsml` identifier is mandatory for every entry, where it uniquely
+identifies the entity within the UnitsML framework.
+
+Other types of identifier types are also supported, such as `type: nist` for
+legacy UnitsML identifiers that start with a prefix of `NIST`.
+
+The UnitsML identifier follows a specific format:
+
+[source,yaml]
+----
+id: {entity-type}:{entity-name}
+type: unitsml
+----
+
+Where,
+
+`entity-type`:: Abbreviated code for the type of entity.
+`u`::: Unit
+`d`::: Dimension
+`p`::: Prefix
+`q`::: Quantity
+`s`::: Scale
+`us`::: Unit system
+
+`entity-name`:: The short name of the entity, typically identical to the
+`short:` attribute of the entity.
+
+The legacy UnitsML identifier ("NIST" prefix) is used for backward compatibility
+and is not required for new entries.
+
+[source,yaml]
+----
+id: NIST{entity-type}{entity-code}
+type: nist
+----
+
+Where,
+
+`entity-type`:: Abbreviated code for the type of entity.
+`u`::: Unit
+`d`::: Dimension
+`p`::: Prefix
+`q`::: Quantity
+
+`entity-code`:: A unique code for the entity. It is a number for units, quantities and
+dimensions, and a string pattern of `{base_number}_{power}` for prefixes.
+
+[example]
+====
+[source,yaml]
+----
+identifiers:
+- id: u:meter
+  type: unitsml
+- id: NISTu1
+  type: nist
+----
+====
+
+
+==== Symbols
+
+The Symbol object represents the notation used to represent the entity in different
+contexts and formats.
+
+The Symbol object is used for units, prefixes, certain quantities and certain dimensions.
+
+A Symbol object contains the following attributes which allow for rendering in
+various formats:
+
+`id`:: A unique identifier identifying the symbol across UnitsDB
+`ascii`:: Plain text ASCII representation
+`unicode`:: Unicode representation, used in UnicodeMath
+`html`:: HTML markup representation
+`mathml`:: MathML markup representation
+`latex`:: LaTeX markup representation
+
+This multi-format approach ensures that the symbols can be rendered correctly
+across various applications and documents.
+
+[example]
+====
+[source,yaml]
+----
+symbols:
+- latex: "\\ensuremath{\\mathrm{m}}"
+  unicode: m
+  ascii: m
+  html: m
+  id: m
+  mathml: "<mi mathvariant='normal'>m</mi>"
+----
+====
+
+==== Localized string
+
+The localized string object represents a human-readable string that can be
+localized into different languages.
+
+It is used for names, descriptions, and other text fields that may require
+translation or localization. Multiple values are allowed per language.
+
+A localized string object contains the following attributes:
+
+`value`:: The localized string value
+`lang`:: The language code (e.g., "en" for English, "fr" for French)
+
+[example]
+====
+[source,yaml]
+----
+names:
+- value: metre
+  lang: en
+- value: meter
+  lang: en
+- value: mètre
+  lang: fr
+----
+====
+
+==== References
+
+A reference object represents a link to an external resource or standard
+that provides additional context or information about the entity.
+
+Currently, UnitsDB units, quantities and prefixes link to:
+
+* the SI Digital Framework
+* UCUM
+
+A reference contains the following attributes:
+
+`uri`:: The URI or URL of the reference
+`type`:: The type of reference (e.g., "normative", "informative")
+`authority`:: The authority responsible for the reference
+
+[example]
+====
+[source,yaml]
+----
+references:
+- uri: http://si-digital-framework.org/SI/units/metre
+  type: normative
+  authority: si-digital-framework
+- type: informative
+  authority: ucum
+  uri: ucum:base-unit:code:m
+----
+====
+
+The SI Digital Framework reference is a normative reference to the
+official SI unit definitions.
+
+SI references are added to:
+
+* units.yaml for units
+* quantities.yaml for quantities
+* prefixes.yaml for prefixes
+* dimensions.yaml for dimensions
+
+
+The UCUM URI format is a custom one used inside UnitsML with the pattern
+`ucum:{type}:{klass}:code:{unit_code}`, and is listed as informative.
+
+UCUM references are added to:
+
+* units.yaml for units
+* prefixes.yaml for prefixes
+
+
+=== Dimensions
+
+==== General
+
+Dimensions represent the fundamental physical quantities that form the basis of
+any measurement system. They are the abstract properties that define the nature
+of a physical quantity, independent of any specific unit of measurement.
+
+* The SI system defines seven base dimensions (length, mass, time, electric
+current, thermodynamic temperature, amount of substance, and luminous intensity).
+
+* A special dimensionless dimension is also defined, which has no physical
+significance but is used in certain contexts.
+
+* Derived dimensions are formed by combining base dimensions through
+multiplication, division, or exponentiation. For example, velocity is a derived
+dimension formed from length and time (L/T), and force is derived from mass
+and acceleration (ML/T²).
+
+A dimension object in `dimensions.yaml` typically has the following structure:
+
+[source,yaml]
+----
+- identifiers:
+  - id: dimension_id
+    type: type_identifier
+  short: short_name
+  {dimension_name}:
+    power: power_numerator
+    symbol: ASCII representation
+    symbols:
+    - ascii: ASCII representation
+      html: "HTML representation"
+      id: dimension_symbol_id
+      latex: "LaTeX representation"
+      mathml: "MathML representation"
+      unicode: "Unicode representation"
+----
+
+For example:
+
+[source,yaml]
+----
+- identifiers:
+  - id: NISTd1
+    type: nist
+  length:
+    power: 1
+    symbol: L
+    symbols:
+    - ascii: L
+      html: "&#x1D5AB;"
+      id: dim_L
+      latex: "\\ensuremath{\\mathsf{L}}"
+      mathml: "<mi mathvariant='sans-serif'>L</mi>"
+      unicode: "\U0001D5AB"
+  short: length
+- identifiers:
+  - id: NISTd2
+    type: nist
+  mass:
+    power: 1
+    symbol: M
+    symbols:
+    - ascii: M
+      html: "&#x1D5AC;"
+      id: dim_M
+      latex: "\\ensuremath{\\mathsf{M}}"
+      mathml: "<mi mathvariant='sans-serif'>M</mi>"
+      unicode: "\U0001D5AC"
+  short: mass
+----
+
+==== Notes
+
+The following dimensions are identified by NIST but they are excluded from
+`dimensions.yaml` since they are unused:
+
+[source,yaml]
+----
+- identifiers:
+  - id: NISTd87
+    type: nist
+  dimensionless: true
+  short: dimensionless
+
+- identifiers:
+  - id: NISTd86
+    type: nist
+  dimensionless: true
+  short: dimensionless
+
+- identifiers:
+  - id: NISTd81
+    type: nist
+  dimensionless: true
+  short: dimensionless
+----
+
+
+=== Prefixes
+
+==== General
+
+Prefixes are modifiers that can be attached to units to indicate decimal
+multiples or submultiples. They provide a concise way to express very large or
+small quantities without resorting to scientific notation.
+
+[example]
+The prefix "kilo" (k) multiplies a unit by 1000, so 1 kilometer equals 1000
+meters.
+
+The SI system defines a set of standard prefixes included in UnitsDB.
+
+A prefix object in `prefixes.yaml` typically has the following structure:
+
+[source,yaml]
+----
+- identifiers:
+  - id: prefix_id
+    type: type_identifier
+  base: base
+  names:
+  - prefix_name
+  short: prefix_short_name
+  power: power
+  symbol:
+    id: symbol_id
+    ascii: ASCII representation
+    html: "HTML representation"
+    latex: "LaTeX representation"
+    unicode: "Unicode representation"
+    mathml: "MathML representation"
+----
+
+For example:
+
+[source,yaml]
+----
+- identifiers:
+  - id: NISTp10_2
+    type: nist
+  base: 10
+  names:
+  - hecto
+  short: hecto
+  power: 2
+  symbol:
+    latex: h
+    unicode: h
+    ascii: h
+    html: h
+    id: hecto
+    mathml: "<mi>h</mi>"
+- identifiers:
+  - id: NISTp10_1
+    type: nist
+  base: 10
+  names:
+  - deka
+  short: deka
+  power: 1
+  symbol:
+    latex: da
+    unicode: da
+    ascii: da
+    html: da
+    id: deka
+    mathml: "<mi>da</mi>"
+----
+
+==== Notes
+
+Decimal prefixes are identified by their power of 10, e.g. `NISTp10_1`
+
+The prefix `NISTp10_0` is a placeholder for unity.
+
+Binary prefixes are identified by their power of 2, e.g. `NISTp2_10`
+
+
+=== Quantities
+
+==== General
+
+Quantities are measurable properties of physical phenomena, objects, or
+substances. They represent the attributes that can be measured and expressed
+with numbers. Each quantity is associated with a specific dimension (or
+combination of dimensions) and can be measured using various units.
+
+The SI system categorizes quantities into two main types:
+
+* Base quantities: The seven fundamental quantities from which all others are
+derived (length, mass, time, electric current, thermodynamic temperature, amount
+of substance, and luminous intensity)
+
+* Derived quantities: Quantities formed by algebraic combinations of base
+quantities (e.g., area, volume, velocity, force)
+
+Each quantity has a unique identity and can be measured in specific units that
+share the same dimension.
+
+[example]
+"length" is a quantity that can be measured in meters, feet, or kilometers.
+
+A quantity can be combined with other quantities to form compound quantities,
+such as velocity (length/time) or force (mass × acceleration).
+
+A quantity object in `quantities.yaml` typically has the following structure:
+
+[source,yaml]
+----
+- identifiers:
+  - id: quantity_id
+    type: type_identifier
+  names:
+  - names
+  quantity_type: {base|derived}
+  short: short_name
+  unit_references:
+  - id: unit_id
+    type: type_identifier
+  dimension_reference:
+    id: dimension_id
+    type: type_identifier
+  references:
+  - uri: http://si-digital-framework.org/quantities/QUANTITY_ID
+    type: normative
+    authority: si-digital-framework
+----
+
+For example:
+
+[source,yaml]
+----
+- identifiers:
+  - id: NISTq8
+    type: nist
+  names:
+  - value: area
+    lang: en
+  - value: superficie
+    lang: fr
+  quantity_type: base
+  unit_references:
+  - id: NISTu164
+    type: nist
+  - id: NISTu165
+    type: nist
+  - id: NISTu1e2/1
+    type: nist
+  - id: NISTu283
+    type: nist
+  - id: NISTu317
+    type: nist
+  - id: NISTu42
+    type: nist
+  - id: NISTu43
+    type: nist
+  - id: NISTu44
+    type: nist
+  - id: NISTu45
+    type: nist
+  - id: NISTu46
+    type: nist
+  dimension_reference:
+    id: NISTd8
+    type: nist
+  references:
+  - uri: http://si-digital-framework.org/quantities/AREA
+    type: normative
+    authority: si-digital-framework
+- identifiers:
+  - id: NISTq166
+    type: nist
+  names:
+  - electric potential
+  quantity_type: derived
+  unit_references:
+  - id: NISTu261
+    type: nist
+  - id: NISTu268
+    type: nist
+  dimension_reference:
+    id: NISTd18
+    type: nist
+- identifiers:
+  - id: NISTq7
+    type: nist
+  names:
+  - luminous intensity
+  quantity_type: base
+  short: luminous_intensity
+  unit_references:
+  - id: NISTu7
+    type: nist
+  dimension_reference:
+    id: NISTd7
+    type: nist
+----
+
+
+=== Units
+
+==== General
+
+Units are standardized quantities used to express measurements of physical
+properties. They provide a reference scale for measuring quantities, allowing
+values to be communicated uniformly. Each unit is associated with a specific
+physical quantity and dimension, and has a defined relationship to other units
+in the same dimension.
+
+The SI system classifies units into several categories:
+
+* Base units: The seven fundamental units corresponding to the base quantities
+(meter, kilogram, second, ampere, kelvin, mole, and candela)
+
+* Derived units: Units formed from combinations of base units (e.g., newton,
+joule, pascal)
+
+* Special named units: Derived units that have been given unique names for
+convenience (e.g., newton for kg·m/s²)
+
+* Units outside the SI: Non-SI units that are accepted for use with the SI
+(e.g., minute, hour, degree)
+
+Units can be combined with prefixes to express multiples or submultiples, and
+can be combined algebraically (through multiplication and division) to form
+compound units.
+
+A unit object in `units.yaml` typically has the following structure:
+
+[source,yaml]
+----
+- identifiers:
+  - id: unit_id
+    type: type_identifier
+  quantity_references:
+  - id: quantity_id
+    type: type_identifier
+  names:
+  - names
+  root: true|false
+  short: unit_short_name
+  symbols:
+  - id: symbol_id
+    ascii: ASCII representation
+    html: "HTML representation"
+    mathml: "MathML representation"
+    latex: "LaTeX representation"
+    unicode: "Unicode representation"
+  dimension_reference:
+    id: dimension_id
+    type: type_identifier
+  unit_system_reference:
+  - id: unit_system_id
+    type: type_identifier
+  # Optional fields for derived units:
+  prefixed: true|false
+
+  # Note: Use either root_units OR si_derived_bases, but not both together
+
+  # Use root_units for composite units that include any non-SI or non-SI-derived units
+  # root_units can also contain SI units
+  root_units:
+  - power: power_numerator
+    unit_reference:
+      id: unit_id
+      type: type_identifier
+    prefix_reference:
+      id: prefix_id
+      type: type_identifier
+
+  # Use si_derived_bases only for composite units that use exclusively SI base units
+  si_derived_bases:
+  - power: power_numerator
+    unit_reference:
+      id: unit_id
+      type: type_identifier
+    prefix_reference:
+      id: prefix_id
+      type: type_identifier
+----
+
+For example:
+
+[source,yaml]
+----
+- identifiers:
+  - id: NISTu5
+    type: nist
+  quantity_references:
+  - id: NISTq5
+    type: nist
+  names:
+  - value: kelvin
+    lang: en
+  - value: kelvin
+    lang: fr
+  root: true
+  short: kelvin
+  symbols:
+  - latex: "\\ensuremath{\\mathrm{K}}"
+    unicode: K
+    ascii: K
+    html: K
+    id: K
+    mathml: "<mi mathvariant='normal'>K</mi>"
+  - latex: "\\ensuremath{\\mathrm{^{\\circ}K}}"
+    unicode: "°K"
+    ascii: degK
+    html: "&#176;K"
+    id: degK
+    mathml: "<mi mathvariant='normal'>&#176;K</mi>"
+  dimension_reference:
+    id: NISTd5
+    type: nist
+  unit_system_reference:
+  - id: si-base
+    type: unitsml
+----
+
+
+=== Scales
+
+==== General
+
+Scales define the mathematical properties of measurement systems and how values
+relate to each other. They specify important characteristics like whether a
+scale has a true zero point, whether equal intervals represent equal
+differences, or whether the scale uses logarithmic relationships.
+
+Understanding the scale type is crucial for proper interpretation of
+measurements and for determining what mathematical operations can legitimately
+be performed on the values.
+
+[example]
+On a ratio scale (like length), you can say that 10 meters is twice as long as 5
+meters. On an interval scale (like Celsius temperature), 20°C is not "twice as
+hot" as 10°C.
+
+UnitsDB defines several scale types including continuous ratio scales,
+continuous interval scales, logarithmic scales, and discrete scales, each with
+specific properties that determine how measurements should be interpreted and
+what mathematical operations are valid.
+
+A scale object in `scales.yaml` typically has the following structure:
+
+[source,yaml]
+----
+- identifiers:
+  - id: scale_id
+    type: type_identifier
+  names:
+  - scale_name
+  short: short_name
+  description:
+  - description of scale type
+  properties:
+    continuous: true|false
+    ordered: true|false
+    logarithmic: true|false
+    interval: true|false
+    ratio: true|false
+----
+
+For example:
+
+[source,yaml]
+----
+- identifiers:
+  - id: continuous_ratio
+    type: unitsml
+  names:
+  - continuous ratio scale
+  short: continuous_ratio
+  description:
+  - A measurement scale with continuous values and a true zero point, allowing for ratio comparisons
+  properties:
+    continuous: true
+    ordered: true
+    logarithmic: false
+    interval: true
+    ratio: true
+- identifiers:
+  - id: logarithmic_ratio
+    type: unitsml
+  names:
+  - logarithmic ratio scale
+  short: logarithmic_ratio
+  description:
+  - A scale where equal ratios appear as equal intervals, with a zero point representing a reference value
+  properties:
+    continuous: true
+    ordered: true
+    logarithmic: true
+    interval: true
+    ratio: true
+----
+
+Units refer to scales using a `scale_reference` object:
+
+[source,yaml]
+----
+scale_reference:
+  id: scale_id
+  type: type_identifier
+----
+
+==== Notes
+
+The following scale types are currently defined:
+
+`continuous_ratio`:: A measurement scale with continuous values and a true zero
+point (most physical quantities)
+
+`continuous_interval`:: A measurement scale with continuous values but an
+arbitrary zero point (e.g., temperature in °C)
+
+`logarithmic_ratio`:: A logarithmic scale where equal ratios appear as equal
+intervals (e.g., decibels)
+
+`logarithmic_field`:: A logarithmic scale used for field quantities that uses
+natural logarithms (e.g., neper)
+
+`discrete`:: A scale consisting of discrete, countable values (e.g., bits)
+
+
+== Unit systems
+
+=== General
+
+Unit systems are coherent collections of units that are used together to express
+measurements in a consistent way. Each unit system has its own set of base units
+and derived units, organized according to specific principles.
+
+The most widely used unit system is the International System of Units (SI), but
+the database also includes information about other unit systems and their
+relationships to SI.
+
+Unit systems help provide context for units, indicating whether they are part of
+the official SI system, acceptable for use with SI (like minutes or degrees), or
+belong to entirely different measurement frameworks (like imperial units). This
+context is important for interoperability and conversion between different
+measurement standards.
+
+In the UnitsDB, units are associated with their respective unit systems through
+references, allowing applications to identify which units belong to which
+systems and to determine compatibility between measurements expressed in
+different systems.
+
+A unit system object in `unit_systems.yaml` typically has the following structure:
+
+[source,yaml]
+----
+- acceptable: {true|false} # whether the unit system is SI acceptable
+  short: short_name
+  identifiers:
+  - id: unit_system_id
+    type: type_identifier
+  name: unit_system_name
+----
+
+For example:
+
+[source,yaml]
+----
+- acceptable: true
+  short: si-compatible
+  identifiers:
+  - id: SI_compatible
+    type: nist
+  name: Units compatible with SI
+- acceptable: true
+  short: si-base
+  identifiers:
+  - id: SI_base
+    type: nist
+  name: SI base units
+----
+
+=== Notes
+
+The following unit systems are currently defined:
+
+`si-base`:: Contains the seven SI base units (meter, kilogram, second, ampere,
+kelvin, mole, and candela). These form the foundation of the SI system.
+
+`si-derived-special`:: Contains SI-derived units with special names and symbols
+(e.g., newton, pascal, joule). These units are derived from base units but have
+been given unique names for convenience.
+
+`si-derived-nonspecial`:: Contains SI-derived units that use combinations of
+base unit symbols without special names (e.g., m/s, kg/m³).
+
+`si-compatible`:: Contains all units that are compatible with the SI system,
+including base units, derived units, and accepted non-SI units.
+
+`nonsi-acceptable`:: Contains non-SI units that are accepted for use with the SI
+system based on the BIPM SI Brochure (e.g., minute, hour, degree).
+
+`nonsi-unacceptable`:: Contains non-SI units that are not acceptable for use
+with the SI system (e.g., deprecated or obsolete units).
+
+`nonsi-nist-acceptable`:: Contains non-SI units that are acceptable according to
+NIST SP 811 but may not be officially accepted by BIPM (e.g., certain customary
+or traditional units).
+
+
+In UnitsDB, a unit can belong to multiple unit systems. This classification
+helps applications determine the appropriate use contexts for each unit.
+
+[example]
+A unit might be categorized as both `nonsi-unacceptable` (meaning it is not
+acceptable for SI usage) but also as `nonsi-nist-acceptable` (meaning NIST SP
+811 considers it acceptable in certain contexts).
+
+When using unit systems in applications, the `acceptable` property can be used
+as a quick filter for SI-compliant units, while more specific categorization can
+be achieved using the individual unit system references.
+
+
+== Contributing
+
+=== General
+
+When contributing to this repository, please follow these guidelines.
+
+=== Proposing a new unit, dimension, or quantity
+
+. Check if the unit already exists in the database.
+. If it does not exist, create a new YAML file in the appropriate directory
+   (e.g., `units.yaml`, `dimensions.yaml`, etc.).
+. Follow the structure outlined in the "Content classes" section.
+. Ensure that the new unit is properly referenced in the relevant files.
+. Add a test case for the new unit in the appropriate test file.
+. Run the tests to ensure everything is working correctly.
+. Submit a pull request with a clear description of the changes made.
+. Include any relevant references or sources for the new unit.
+. Ensure that the pull request is against the `main` branch of the repository.
+. Wait for review and feedback from the repository maintainers.
+. Address any comments or suggestions made during the review process.
+. Once approved, the pull request will be merged into the main branch.
+
+
+=== Database normalization
+
+For ease of use, the database is normalized to avoid redundancy and ensure
+consistency.
+
+UnitsDB uses the `unitsdb` gem to normalize the database.
+
+NOTE: The `--sort=nist` option ensures that the output is sorted according to
+legacy NIST identifiers for stability reasons, which may change in the future.
+
+Please run the following commands to ensure that the database is
+normalized before submitting a pull request:
+
+[source,bash]
+----
+$ gem install unitsdb
+
+$ unitsdb _modify normalize --all --database={unitsdb_yaml_dir} --sort=nist
+
+Normalized {unitsdb_yaml_dir}/dimensions.yaml
+Normalized {unitsdb_yaml_dir}/prefixes.yaml
+Normalized {unitsdb_yaml_dir}/quantities.yaml
+Normalized {unitsdb_yaml_dir}/unit_systems.yaml
+Normalized {unitsdb_yaml_dir}/units.yaml
+All YAML files normalized successfully!
+
+----
+
+=== Database validation
+
+All YAML files must be validated before submitting a pull request.
+
+UnitsDB uses the `unitsdb` gem to validate the database.
+
+[source,bash]
+----
+# Validate all references
+$ unitsdb validate references --database={unitsdb_yaml_dir}
+
+# Validate all identifiers
+$ unitsdb validate identifiers --database={unitsdb_yaml_dir}
+
+# Check for duplicate SI references:
+$ unitsdb validate si_references --database={unitsdb_yaml_dir}
+----
+
+=== Creating release files
+
+When preparing an official release of UnitsDB, create unified release files for
+users.
+
+UnitsDB uses the `unitsdb` gem to create release files.
+
+[source,bash]
+----
+# Create both unified YAML and ZIP archive files
+$ unitsdb release --database={unitsdb_yaml_dir} --output-dir=release
+
+# Create only unified YAML file
+$ unitsdb release --format=yaml --database={unitsdb_yaml_dir} --output-dir=release
+
+# Create only ZIP archive
+$ unitsdb release --format=zip --database={unitsdb_yaml_dir} --output-dir=release --version=2.1.0
+
+# Specify a version (required, must be in semantic format x.y.z)
+$ unitsdb release --version=2.1.0 --database={unitsdb_yaml_dir} --output-dir=release
+----
+
+=== Automated releases with GitHub Actions
+
+This repository includes a GitHub Actions workflow that automatically creates
+release artifacts when a new version tag is pushed. To create a new release:
+
+. Tag the repository with the version number (prefixed with 'v'):
++
+[source,bash]
+----
+$ git tag v2.1.0
+$ git push origin v2.1.0
+----
+
+. The GitHub Actions workflow will automatically:
+
+** Generate the unified YAML file
+** Create a ZIP archive of all database files
+** Upload both files as release assets
+** Create a GitHub release with the tag name
+
+The release artifacts will be available on the GitHub releases page.
+
+The unified YAML file combines all database files into a single file for easier
+integration:
+
+[source,yaml]
+----
+schema_version: "2.0.0"
+version: "2.1.0"
+dimensions:
+  - identifiers: [...]
+    length: {...}
+    names: [...]
+  # ...
+prefixes: [...]
+quantities: [...]
+units: [...]
+unit_systems: [...]
+----
+
+This unified format makes it more convenient for users to work with the entire
+database while ensuring all components are compatible with each other.
+
+The ZIP archive contains all individual database files for users who prefer to
+work with separate files.
+
+Both release formats include version information in their filenames (e.g.,
+`unitsdb-2.0.0.yaml` and `unitsdb-2.0.0.zip`).
+
+
+== Copyright and license
+
+Copyright CalConnect. Incorporates public domain work from NIST.
+
+This work is licensed under the Creative Commons Attribution 4.0 International
+License. To view a copy of this license, visit
+https://creativecommons.org/licenses/by/4.0/[CC-BY 4.0]