#Contribution Guide

This document helps you quickly develop, test, and submit PRs in this repository. The repository uses a Monorepo managed by Rush + pnpm, and the documentation site is built with Rspress.

#Setting Up the Development Environment

1. Install Node.js 18+ (LTS/Hydrogen recommended)

   nvm install lts/hydrogen
   nvm alias default lts/hydrogen # Set as the default Node version
   nvm use lts/hydrogen

2. Clone the repository locally

   git clone git@github.com:bytedance/flowgram.ai.git

3. Install global dependencies

   npm i -g pnpm@10.6.5 @microsoft/rush@5.150.0

4. Install project dependencies

   rush install

5. Build the project

   rush build

6. Run the documentation or examples

   rush dev:docs                  # Start the documentation site in apps/docs (with incremental build)
   rush dev:demo-fixed-layout     # Run the fixed layout example
   rush dev:demo-free-layout      # Run the free layout example

#Common Commands (Rush Custom)

rush build            # Build all packages
rush build:watch      # Incrementally build and watch
rush lint             # Run ESLint checks
rush lint:fix         # Automatically fix ESLint issues
rush ts-check         # TypeScript type checking
rush test             # Run test scripts for each package (aggregated by package)
rush e2e:test         # Run all e2e tests
rush e2e:update-screenshot # Update e2e snapshots
rush dep-check        # Automatically check dependency health

#Branch and Commit Conventions

• Branch naming:
  • feat/description (new feature)
  • fix/description (bug fix)
  • docs/description (documentation changes)
  • chore/description (maintenance/miscellaneous)
• Commit messages (Conventional Commits):

  • Format: type(scope): subject, for example:

    feat(editor): Support batch alignment of nodes

  • Common types: feat, fix, docs, style, refactor, test, chore

  • The repository has commitlint validation enabled (commit-msg hook), so commit messages will be automatically checked; pre-commit will also run lint-staged (automatically update license headers, fix eslint issues) and rush check.

#Development and Quality Assurance

• Local development recommendations:
  • First, run rush build:watch, then run the development command in the corresponding demo or docs directory (e.g., rush dev:docs).
  • After modifying the code, ensure it passes: rush lint, rush ts-check, rush build, rush test.
• Testing instructions:
  • e2e test cases are located in the e2e/ directory and can be run with rush e2e:test, or you can update snapshots with rush e2e:update-screenshot.

#Pull Request Process

1. Create your working branch from main (following the branch naming conventions).
2. Code and add tests/documentation.
3. Pass local quality checks (lint, ts-check, build, test).
4. Submit a PR: fill in the description, link the Issue, and use the template.
5. Review and CI: Maintainers will review the code, and it can be merged after the CI passes.

#Documentation Contribution

• Documentation location: apps/docs/src/zh/** (Chinese) and apps/docs/src/en/** (English).
• Local preview: Run rush dev:docs to start the Rspress documentation site.
• To automatically generate API documentation, you can run rushx docs in the apps/docs directory (which calls a script to generate it).

#Common Issues

• pnpm-lock merge conflicts: The repository has a merge strategy configured in the post-checkout hook, which usually avoids lock file conflicts.
• Node version: Please ensure you are using Node 18+, otherwise you may encounter dependency or build failures.

#Reporting Issues

• Please submit an Issue on GitHub: https://github.com/bytedance/flowgram.ai/issues/new/choose
  • Describe the problem, reproduction steps, expected and actual behavior, and provide a code example if necessary.

#License

• This project is licensed under the MIT License. By submitting code, you agree to the relevant terms.