meta-unit-core/CONTRIBUTING.md

Contributing to meta-unit-core

中文

We warmly welcome your contributions to meta-unit-core, the foundational microkernel for the Dao OS. Your efforts help shape the future of CyberLife computation!

---

1. Before You Contribute

Before you start, please take a moment to review these guidelines:

• Code of Conduct: Please read and adhere to our Code of Conduct (coming soon). We are committed to fostering an open and welcoming environment.
• Development Guide: Set up your development environment by following our Development Guide. This ensures you have all the necessary tools and a consistent setup.
• Understand the Vision: Familiarize yourself with the overall vision of the Dao Operating System Project and how meta-unit-core fits into it.

---

2. How to Contribute

We follow a Trunk-Based Development (TBD) workflow to ensure rapid iteration and continuous integration.

Reporting Bugs

If you find a bug, please open an issue on our Gitea Issue Tracker.

• Search First: Check existing issues to see if the bug has already been reported.
• Clear Description: Provide a clear and concise description of the bug.
• Steps to Reproduce: Include detailed steps to reproduce the bug.
• Expected vs. Actual Behavior: Describe what you expected to happen and what actually happened.
• Environment: Provide details about your environment (OS, Rust version, Docker version, etc.).

Suggesting Enhancements or New Features

We love new ideas! If you have a suggestion:

• Open an Issue: Describe your idea in detail on the Issue Tracker.
• Justification: Explain why this enhancement or feature would be valuable to the project.
• Potential Design: If you have thoughts on how it could be implemented, include them.

Your First Code Contribution

For your first contribution, consider looking for issues marked with good first issue or help wanted on our Issue Tracker.

Code Contribution Workflow (TBD)

1. Pull Latest Main: Always start by fetching and pulling the very latest changes from the main branch to your local machine.

   git pull origin main
   

2. Create a Short-Lived Feature Branch: For your local development, create a new branch. This branch should focus on a single, small, atomic change and be merged back into main quickly.

   git checkout -b feature/my-new-awesome-thing
   # Or for a bug fix:
   git checkout -b bugfix/fix-that-issue
   

   Naming Convention: Prefer feature/, bugfix/, docs/, refactor/ prefixes.
3. Develop & Test:
   • Test-Driven Development (TDD): We encourage writing tests before writing the code to ensure correctness and maintainability.
   • Make small, logical commits with clear commit messages.
   • Ensure all existing tests pass (cargo test).
   • Add new tests for your changes.
4. Format and Lint: Before committing, ensure your code adheres to our style guidelines.

   cargo fmt --all           # Apply formatting changes
   cargo clippy --all-targets --all-features -- -D warnings # Run linter, treating all warnings as errors
   

5. Push Your Branch:

   git push origin your-branch-name
   

6. Create a Pull Request (PR):
   • Go to our Gitea repository and create a new Pull Request from your branch to the main branch.
   • PR Title: Use a clear, concise title summarizing your changes.
   • PR Description: Provide a detailed description of your changes, why they were made, any relevant issue numbers, and how to test them (if applicable).
   • CI Checks: Ensure all Continuous Integration (CI) checks pass.
7. Fast Review & Merge: Your PR will be reviewed quickly. Once approved and CI passes, it will be merged into main. We aim for small, frequent merges.
8. Use Feature Flags for Large Features: For larger or incomplete features that span multiple PRs or development cycles, commit directly to main but wrap the new code with feature flags. This ensures the main branch always remains stable and releasable.

---

3. Code Style and Conventions

• Rust Format: We use rustfmt to enforce code style. Always run cargo fmt before committing.
• Clippy: We use clippy for linting. All clippy warnings must be resolved (cargo clippy --all-targets --all-features -- -D warnings).
• Commit Messages: Follow a clear and concise commit message convention (e.g., Conventional Commits).
  • Example: feat: Add new IPC mechanism or fix: Resolve race condition in task scheduler
• Documentation: All public functions, structs, enums, and modules should have clear Rustdoc comments (///). Examples are highly encouraged.

---

4. Community and Communication

• Issue Tracker: https://nest.doylee.cn/dao-os/meta-unit-core/issues (for bugs, features, and discussions)
• Chat/Forum: (Consider adding a Discord, Matrix, or forum link here if you set one up)
• Pull Requests: Used for submitting code changes.

Thank you for your interest in contributing to meta-unit-core! We look forward to your contributions.

---