Contributing

Thanks for your interest in Unix Architecture! This template is open-sourced under the MIT license. Issue reports and PR contributions are welcome.

Prerequisites

• HBuilderX 5.34+ (the uni-app x compiler ships with HBuilderX)
• Git
• Node.js 20+ and pnpm (only needed for building the docs site)

Workflow

1. Fork and clone the repository, then branch off master (naming: feature/<name>);
2. Configure and run following Quick Start (use the mock protocol while the backend is not ready);
3. Open a Pull Request to master when done.

Code Conventions

All engineering constraints are documented in Architecture and Conventions. Before submitting, double-check:

• Layered call chain: page → composable → store → api → utils/request; pages never touch the network layer directly;
• UTS red lines: every one of them corresponds to a real compile error or runtime crash — required reading;
• Verification DoD: changes to api / stores / composables must be compile-verified; interactive changes must be walked through in the browser with request logs checked;
• Template purity: docs/ and .trae/ are self-contained directories that can be deleted as a whole; business code must never depend back on them.

Documentation Contributions

The docs site lives in docs/ (VitePress). For local development:

cd docs
pnpm install
pnpm run dev      # local preview
pnpm run build    # build verification

Notes:

• Bilingual sync: when changing a Chinese page (src/), update the matching English page (src/en/) in the same change; sidebar entries on both sides are maintained in .vitepress/config/{zh,en}.ts;
• Avoid bare ASCII angle brackets in prose (e.g. <token>) — the Vue template compiler treats them as HTML tags and fails the build; wrap them in inline code or rewrite;
• Site assets go in src/public/ (publicDir resolves relative to srcDir).

Commit Conventions

• Commit messages: <type>: Chinese description, with type among feat / fix / docs / refactor etc.;
• User-visible changes must update the root CHANGELOG.md (Keep a Changelog style: Added / Changed / Fixed / Verified);
• One PR focuses on one thing; keep changes minimal.

AI-Assisted Contributions

This template ships with an AI-assisted development system (see AI-Assisted Development). Code generated by AI tools is bound by the same architecture red lines — the rule files live in .trae/rules/; before contributing, confirm the generated code does not bypass layering or fall into the pitfalls in the UTS red-line checklist.

Reporting Issues

• Bugs and feature requests: Issues — please include the HBuilderX version, target platform (Web / Android), and minimal reproduction steps;
• Usage questions: check the FAQ and the guide pages first.