Contributing
Umi‑Time provides a shared universal representation of time while preserving locally meaningful interpretation and optional solar context.
As an open standard ecosystem, contributions are welcome from developers, writers, designers, educators, translators, and anyone interested in helping make Umi‑Time more understandable and accessible.
Project Architecture
The project is modularized across independent, specialized repositories:
- umi-time/spec — The canonical, self‑contained standard defining the Umi‑Time model, including universal time representation, local interpretation, solar context, mathematical formulas, and canonical formats.
-
umi-time/www — The primary
public website, the Manifesto, and the presentation layers (Clock, Map,
Geometry). It embeds the
specrepository dynamically via a Git submodule. - umi-time/umi-time-js — The reference JavaScript/TypeScript implementation library for core parsing, calculation, and rendering.
Contributing to the Specification Standard
Because the spec repository maintains the immutable standard,
changes to formulas or core architectures follow a strict protocol. Typos,
formatting bugs, or ambiguities can be submitted directly via an Issue in
the spec repository. Architectural adjustments require community
consensus on a Discussion thread prior to drafting a Pull Request.
Getting Started with the Website
To contribute to the website layout, documentation text, or interactive tools, clone the web repository locally:
git clone https://github.com/umi-time/www.git
cd www
git submodule update --init --recursive
npm install
Important First-Time Setup Note: Our astro.config.mjs features an automated asset sync script that mirrors submodule layouts
and MathJax layouts into your active public/ tree. **You must
run the compilation sequence at least once** to populate these asset structures
properly before initializing your dev server:
npm run build
Once compiled, start Astro's local hot-reloading development loop:
npm run dev
Website Contributions
The primary public interface lives in the www repository and
is powered by Astro. Impactful contributions include:
- Improving documentation copy and text layout readability.
- Resolving responsive design framework or styling bugs across viewports.
- Enhancing interactive demonstrations, including analog clock, cartographic, and solar‑context visualizations.
- Drafting new implementation examples, setup recipes, or technical tutorials.
Making Changes
Before opening a pull request on any repository:
- Ensure TypeScript builds cleanly without errors
- Run the repository test suite if applicable
- Follow existing code style and naming conventions
- Update documentation if your change affects a public API or interface behavior
Coding & Documentation Standards
- Universal First: Keep the underlying time representation mapped strictly to UTC. Never write regional adjustments into Layer 1 data.
- Layer Separation: Treat universal time, local interpretation, and solar context as distinct concerns. Changes in one layer should not modify another.
- Presentation Agnostic: Interface logic should support analog, digital, textual, cartographic, and future presentation forms without making any single representation fundamental.
-
Zero JS Footprint by Default: The specification page
parses static raw HTML elements server-side via Astro's
set:htmldirective. Keep script inclusions tightly scoped.
Library Coding Standards
When contributing code to the umi-time-js core reference library,
adhere to these architectural rules:
- Use TypeScript for all core library code.
- Prefer pure functions for solar geometry and time conversion calculations.
-
Keep the
UmiTimeengine immutable—all transformation methods must return new instances. - Document public methods explicitly with clear intent, parameter definitions, and geometric units.
- Write comprehensive tests for any new local-interpretation, solar-context, coordinate-mapping, or astronomical calculation functions.
- Ensure all formatting spec constants remain strictly synchronized with the canonical Umi‑Time standard.
Pull Requests
Every pull request should:
- Build successfully inside its independent repository pipeline
- Pass all validation checks and tests
- Include updated documentation if needed
- Reference related issues or discussions
Keep PRs focused. Small, well-scoped changes are significantly easier to review and merge.
Issues & Feature Requests
If you find a bug or want to propose a feature, open an issue on the specific repository matching the component.
Please include:
- Clear reproduction steps
- Expected vs actual behavior
- Environment details (browser, OS, Node version)
- Any relevant Umi‑Time input values or coordinates
Thank You
Umi‑Time is a voluntary, collaborative effort to refine how a connected species communicates about time. Whether you’re correcting an equation typo, translating document layouts, or constructing a client library, your help is deeply appreciated.