← Về thư mục

Contributing to OpenMAIC

Thank you for your interest in contributing to OpenMAIC! This guide will help you get started and ensure a smooth collaboration.

How to Contribute

Contribution type	What to do
Bug fix	Open a PR directly (link the issue if one exists)
Extending existing features (e.g. adding a new model provider, new TTS engine)	Open a PR directly
New feature or architecture change	Start a GitHub Discussion or ask in Discord before opening a PR
Design / UI change	Discuss in a GitHub Discussion or Discord first — include mockups or screenshots
Refactor-only PR	Not accepted unless a maintainer explicitly requests it
Documentation	Open a PR directly
Question	Ask in Discord

Claiming Issues

To avoid duplicate effort, please comment on an issue to claim it before you start working. A maintainer will assign you.

• If no PR or meaningful update (WIP commit, progress comment) appears within 1 day, the issue may be reassigned to someone else.
• If you see an issue already assigned, reach out to the assignee first to coordinate — you may be able to collaborate or split the work.
• If you can no longer work on a claimed issue, please leave a comment so others can pick it up.

Prerequisites

• Node.js >= 20.9.0
• pnpm (latest)
• A copy of .env.local — see .env.example for reference

Getting Started

# Clone the repository
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your API keys

# Start the development server
pnpm dev

Development Workflow

1. Fork the repository and create a branch from main: bash git checkout -b feat/your-feature main
2. Branch naming convention:
3. feat/ — new features or enhancements
4. fix/ — bug fixes
5. docs/ — documentation changes
6. Make your changes and test locally.
7. Run all CI checks before committing (see below).
8. Open a Pull Request against main.

Environment Variable Changes

When adding or renaming an operator-facing environment variable, update .env.example in the same PR. Document whether it is optional, its safe default or example value, and whether it is read at build time or runtime. Variables used only by tests, CI, or internal development scripts do not need to be added to the template, but their owning file or documentation must make that limited scope clear.

Before You Submit a PR

Run the following checks locally — CI will run them too, but catching issues early saves everyone time:

# 1. Format code
pnpm format

# 2. Lint (with auto-fix)
pnpm lint --fix

# 3. TypeScript type checking
npx tsc --noEmit

If formatting or lint auto-fixes produce changes, include them in your commit.

Local Testing

Before marking a PR as Ready for Review, you must:

1. Verify your goal — confirm that the PR achieves what it set out to do (bug is fixed, feature works as expected, etc.)
2. Regression test — manually check that existing functionality is not broken by your changes (e.g. navigate key flows, verify related features still work)
3. Run CI checks locally (see above)

If you have not completed local verification, keep your PR in Draft status. Only move it to Ready for Review once you are confident it works and does not regress other features.

PR Guidelines

• Every PR must link to an issue — use Closes #123 or Fixes #456 in the PR description. If no issue exists yet, create one first. PRs without a linked issue will not be reviewed.
• Keep PRs focused — one concern per PR; do not mix unrelated changes
• Describe what and why — fill out the PR template
• Include screenshots — for UI changes, show before/after
• Ensure CI passes before requesting review
• All UI text must be internationalized (i18n) — do not hardcode user-facing strings

Commit Message Convention

We follow Conventional Commits:

<type>(<scope>): <short description>

[optional body]

[optional footer]

Types: feat, fix, docs, refactor, test, chore, ci, perf, style

Examples:

feat(tts): add Azure TTS provider
fix(whiteboard): prevent canvas from resetting on window resize
docs: add CONTRIBUTING.md

Changing a Published Package

Four packages under packages/@openmaic/ are published to npm: dsl, storage, renderer, and importer. Anything that ships inside one of those tarballs is under version control in the literal sense — the version number on npm has to keep meaning "this exact source".

If your PR changes a publishable file in one of those packages, bump that package's version in its package.json in the same PR. CI enforces this, and without the bump you will see:

<package>: publishable package inputs changed but version did not increase

What counts as publishable: everything under the package directory except files that never reach the tarball, such as docs/, test/, and vitest.config.ts. Editing only those needs no bump. The exact set lives in scripts/check-package-version-bumps.mjs.

Choosing the number is a semver judgement, and it is yours to make rather than something CI can infer:

• patch — a fix that changes no documented behaviour
• minor — new behaviour that existing consumers can ignore
• major — anything an existing consumer must react to

For packages below 1.0.0, a minor bump signals a breaking change and a patch bump signals a compatible change, following common 0.x semver practice; the major rule applies from 1.0.0.

Be deliberate with @openmaic/dsl. It is the contract the other packages and downstream deployments validate against, so a change that narrows what an existing document may contain is a breaking change even when the diff looks small.

You never publish anything yourself. Once your PR is merged, a version that is not yet on the registry is released automatically, and a @openmaic/<name>@<version> tag is written afterwards to record it. That tag is a marker, not a trigger: pushing one does not release anything.

AI-Assisted PRs 🤖

PRs built with AI tools (Codex, Claude, Cursor, etc.) are welcome! We just ask for transparency and self-review:

• Mark it — note in the PR title or description that the PR is AI-assisted
• AI-review your own code first — before requesting maintainer review, run an AI code review (e.g. Claude, Codex, Copilot) on your changes and address the findings. This is required for AI-assisted PRs to avoid dumping large amounts of unreviewed generated code on maintainers.
• You are responsible for what you submit — understand the code, not just the prompt.

AI-assisted PRs are held to the same quality standard as any other PR. Community members are also encouraged to leave constructive feedback on any PR — peer review helps everyone improve.

Project Structure

OpenMAIC/
├── app/              # Next.js app router pages and API routes
├── components/       # React components
├── lib/              # Shared utilities and core logic (i18n in lib/i18n/locales/)
├── packages/         # Internal packages (mathml2omml, pptxgenjs)
├── public/           # Static assets
└── .github/          # Issue templates, PR template, CI workflows

Reporting Bugs

Use the Bug Report issue template. Include:

• Steps to reproduce
• Expected vs. actual behavior
• Browser / OS / Node version
• Screenshots or error logs if applicable

Requesting Features

Use the Feature Request issue template. For larger features, please open a Discussion first.

Security Vulnerabilities

Please report security vulnerabilities through GitHub Security Advisories. Do not open a public issue for security vulnerabilities.

License

By contributing to OpenMAIC, you agree that your contributions will be licensed under the MIT License.