Skip to content
inhandnetPublic

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Mo documentation

简体中文

Software and hardware documentation sources for the Mo series. This repository maintains guides, specifications, media, design files, evidence and authoring metadata. The single Docusaurus website, standard components, search, previews and deployment are maintained in developer.

The unified website serves all documentation, including hardware pages and their downloads, under /docs/. The test platform is developer.inhand.online; the production target is developer.inhand.com, subject to infrastructure and release acceptance. The website is pre-release, so legacy /hardware-docs/ routes and old attachment paths are not kept; mo-docs releases contain content and do not deploy a website.

Inside mo-docs

Content sources and the unified website

Location Maintained content
docs/ Software guides, FAQ, board sections, shared Markdown/MDX and category metadata
static/ Screenshots, licensed media, evidence and compatibility downloads
hardware/products/, hardware/accessories/ Hardware specifications, interfaces, schematics, mechanical files and accessories
hardware/training/ Maintenance training; excluded from product navigation
content/hardware-map.json Hardware source-to-document route and public asset mapping
validation/ Generated copy of a fixed developer content contract, with commit and hashes
scripts/, tests/, .github/ Content and resource validation, repository governance and content releases

Write normal Markdown. Use registered components for tabs, media, downloads and version tables; component implementation belongs in developer. Shared content and media imports are allowed. Hooks, network requests, arbitrary JavaScript, inline styles and imports from developer's internal src/ are rejected by the content contract. Teaching code inside fenced code blocks is unaffected. Excel remains a source document or attachment; new structured web data uses JSON.

Each file has one maintained source under hardware/; content/hardware-map.json places hardware pages and assets in the /docs/ navigation. Training and source/license evidence remain in the repository.

Mo series repository architecture

Mo repository ownership and unified website

Repository Maintained source Delivery responsibility
developer · GitLab Website components, routes, search, integration and contracts The complete website, release composition and deployment
mo-docs Software/hardware tutorials, specifications, media, design files and training Versioned content and reference assets
mo-tools Toolchain/SDK selection, environment setup, reusable tools and Studio Tool metadata and source packages
mo-models Model catalog, compilation resources, compatibility and raw benchmarks Model references, evidence and artifact status
mo-examples Complete examples with related firmware, clients and configuration Example sources and their requirements
Mo* · product repositories Each product's BSP, drivers, root filesystem, image build and flashing Product images and checksummed release metadata

Mo* covers independently maintained product repositories such as Mo62A, Mo68A, Mo69A, Mo67A, Mo3588 and Mo3568. The framework does not fix their number. Hardware content and maintainer training are maintained in mo-docs.

Each source repository publishes ordinary versions. Developer alone has website RC/final channels. The target composition binds developer + mo-docs + mo-tools + mo-models + mo-examples + selected Mo* to exact commits and consumed-asset hashes. A new source release does not change an already frozen website combination. Tutorial applicability, PCB revisions, image versions and actual validation remain distinct.

Repository protection

Operation Write Admin
Create, update or delete a topic branch Allowed Allowed
Open a PR to master Allowed Allowed
Merge to master Not allowed After required CI passes
Merge one's own PR Not allowed Same checks; no second approval required
Direct push, force-push or delete master Not allowed Blocked by the PR/check ruleset
Create remote Tags and start releases Not allowed Allowed; Tag CI validates after push

GitHub uses two rulesets for master and two for all Tags. Permissions and merge checks are separate because bypass permissions apply to an entire ruleset.

Ruleset Scope Rules / bypass
admin-only-master-updates refs/heads/master Restricts creation/update/deletion/force-push; only Admin has bypass
master-pr-and-required-checks refs/heads/master PR, up-to-date required checks, no deletion or force-push; no bypass; required approvals: 0
admin-only-tags All Tags Restricts creation/update/deletion/force-push; only Admin has bypass
tags-immutable All Tags No updates, deletion or force-push; no bypass

Required checks are commit-message and validate-content. Topic branches have no additional ruleset restriction. The repository automatically deletes eligible source branches after PR merge. Merge, squash and rebase remain available; when squashing, use the validated PR title and a conforming optional body, including room for GitHub's PR-number suffix.

Local hooks provide early feedback and can be bypassed locally; CI is the merge gate. Admins who can edit repository settings remain trusted operators. The separate immutable-Tag rule has no bypass: published Tags and Releases must not be rewritten or deleted in this workflow. Use a new ordinary version for corrections. No local or server-side Tag-creation hook is installed; an invalid Tag remains visible but fails CI before publication.

English commit messages and Changelog

fix(download): keep the image and checksum on the same release

An English Conventional Commit title is sufficient. Add an English body when useful. Types are feat, fix, perf, docs, style, refactor, test, build, ci, chore, revert and sync; the lowercase scope is optional. Keep the title within 72 characters, start the subject with a lowercase letter and omit a final period. Separate a body with a blank line and wrap prose at 72 characters, except URLs and indented code. Do not add credentials, private infrastructure, Co-Authored-By or CI-skip markers.

npm ci installs this clone's commit-msg and pre-push hooks, so invalid messages fail at git commit, including git commit -m. CI checks the PR title and new non-merge commits again. Historical commits before the policy boundary are not rewritten. The policy is in repository-policy.json and policy.mjs.

Release notes use English entries in both editions. Only fixed headings and categories are translated, for example Features / 新功能, Fixes / 修复 and Documentation / 文档. Historical Message: en and Message.en: summaries remain readable; new commits do not need bilingual blocks. generate-changelog.mjs computes the range after the preceding ordinary release. Historical RCs remain traceable but are not a channel for new releases.

Translation API (planned)

Platform Translation server Status
GitLab - To be integrated
GitHub - To be integrated

These are placeholders for future translation of change entries. The current generator runs without a translation API or credentials.

From a change to a release

Content publication and website composition

  1. Edit the owning source and open a PR. Content rules, downloadable-resource tests and commit policy must pass.
  2. An Admin merges after required CI. Use developer's integrated preview to check affected pages and links; mo-docs has no independent website build.
  3. Check remote Tag availability, then create an annotated VX.Y.Z Tag on an accepted master commit. New RC Tags are rejected; historical RCs remain unchanged.
  4. CI validates and packages a content archive, file hashes, release metadata and bilingual-heading Changelogs, then publishes a complete ordinary GitHub Release through a draft.
  5. Developer selects that release in a subsequent website composition, builds and validates the complete site, then owns its release and deployment.

Assets are mo-docs-VERSION-content.tar.gz, content-manifest.json, release.json, CHANGELOG.en.md, CHANGELOG.zh-CN.md, release-notes.md and SHA256SUMS. They contain no site build or deploy credentials. Manual dispatch validates/packages without publication. Published Tags and assets are immutable; inspect failed draft publication before retrying and never overwrite a completed release.

Local authoring

nvm use
npm ci
npm test
# Install dependencies once in a sibling developer checkout, then:
npm run preview -- --port 8051

Set DEVELOPER_DIR if the website checkout is elsewhere. Preview runs developer with this mo-docs directory as a local source override and refreshes edited content. Full website builds, browser checks and search indexing run in developer. npm run docs:diagrams regenerates the bilingual README diagrams.

See CONTRIBUTING.md, ARCHITECTURE.md and SECURITY.md. Content is CC BY-SA 4.0; third-party notices remain in static/ASSETS.md and beside their source files.

Status and diagrams

Website implementation lives in developer. Executable tutorial resources belong to mo-tools, mo-models and mo-examples; content/resource-map.json tells developer where to publish them under /docs/downloads/. This repository retains prose, images, design attachments and declarative firewall configuration. Developer release freezing and full-site rollout have separate acceptance.

Diagram source is maintained centrally in developer/scripts/render-architecture.mjs. Run npm run docs:diagrams, setting DEVELOPER_DIR if necessary, to regenerate this repository's six bilingual SVGs.

Specification data

Maintain Mo62A specifications in specifications.json. Developer generates hardware documentation, product cards and specification tables from this file. OS and kernel versions come from pinned Mo62A release metadata. Integration expands the product-specifications marker; do not maintain a second specification table in prose.

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages