This repository was archived by the owner on May 29, 2026. It is now read-only.
docs: align CONTRIBUTING.md with pnpm/Turborepo stack - #236
Merged
Conversation
The initial CONTRIBUTING.md added in #193 documented npm + a `main` branch + a generic style guide, none of which match the repo's actual conventions. New contributors following it would fail on the first `npm install`, then again at the commitlint hook. This rewrite covers what's actually enforced today: - pnpm 10.22 + Turborepo, Node engines (≥18 for dev, ≥20.19/≥22.13/≥24 for release). - `master` as the base branch. - Conventional Commits enforced by husky + commitlint, with the allowed type list and example subjects. - antfu ESLint rules that actually flag PRs: `I`-prefixed interfaces, `_`-prefixed private members, 4-space indent, complexity caps, the `pnpm check-circular` gate. - Real command surface: `pnpm dev/build/test/coverage/lint/lint:types/ lint:css/check-circular/e2e/e2e:ui` and the scoped `--filter @muyajs/core test:spec[:commonmark|:gfm]` runs. - Repository layout (packages/core as the only source package today, examples/, e2e/, stub packages), with a pointer to CLAUDE.md for architecture. - A "before opening a PR" checklist that mirrors what reviewers ask for in practice (lint, types, tests, check-circular, e2e/spec when relevant, MIGRATION.md updates for public-API changes). - Issues-only support routing (Discussions are not enabled on this repo). Refs #193.
There was a problem hiding this comment.
Pull request overview
Updates CONTRIBUTING.md to match Muya’s current monorepo tooling and contribution workflow (pnpm + Turborepo, enforced commit conventions, and the repo’s actual dev/test commands), so new contributors aren’t following outdated instructions.
Changes:
- Rewrites setup instructions to use pnpm/corepack + Turbo tasks and documents the repo layout (packages/examples/e2e/docs).
- Adds an actionable command cheat sheet (dev/build/test/coverage/lint/types/css/circular/e2e) plus scoped core test runs.
- Documents contribution expectations (Conventional Commits types, PR checklist, and key coding conventions enforced by ESLint/CI).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| By participating in this project, you agree to abide by our code of conduct. We expect all | ||
| contributors to be kind, treat each other with respect, and forgive mistakes. | ||
| Be kind, assume good intent, and keep discussions on-topic. Personal attacks, harassment, and discriminatory language are not welcome. Reports about violations can be sent to the maintainers via a GitHub DM or by opening a confidential issue. |
Member
Author
There was a problem hiding this comment.
Good catch — fixed in 90b4a88. The Code of Conduct section now points at GitHub's abuse reporting flow and the maintainer email in package.json instead.
| | `pnpm dev` | Boot the examples Vite dev server (`turbo dev:demo`). | | ||
| | `pnpm build` | `tsc && vite build` in `packages/core`. Emits `lib/{es,umd,cjs}` and `lib/types`. | | ||
| | `pnpm test` | Vitest unit tests (`--passWithNoTests`). | | ||
| | `pnpm coverage` | Vitest with V8 coverage. | |
Member
Author
There was a problem hiding this comment.
Confirmed — packages/core/vite.config.ts line 26 sets provider: 'istanbul' and the dep is @vitest/coverage-istanbul. Fixed in 90b4a88.
| - Base branch is `master` (not `main`). | ||
| - Use a Conventional-Commit-style title (it becomes the squash commit subject). | ||
| - Describe the **why** in the body, not just the **what** — the diff already shows the what. Link related issues with `Closes #123` / `Refs #123`. | ||
| - Pre-commit, `lint-staged` runs `eslint --fix` on staged `*.ts` and `stylelint --fix` on staged `*.{html,css}`. If a hook fails, fix the issue and create a new commit — **don't bypass with `--no-verify`** unless a maintainer asks you to. |
Member
Author
There was a problem hiding this comment.
Right — .lintstagedrc is just {"*.ts": ["eslint --fix"], "*.css": ["stylelint --fix"]}, no HTML glob. Fixed in 90b4a88 and added a pointer to the file.
| ## Testing | ||
|
|
||
| # Style Guide | ||
| - **Unit tests** live next to their source in `packages/core/src/**/__tests__/` or `*.test.ts`, run with Vitest under `happy-dom`. New parser logic, state transforms, and pure helpers should ship with unit coverage. |
Member
Author
There was a problem hiding this comment.
Confirmed — vite.config.ts doesn't set a global Vitest environment. A quick grep shows 23 of 47 test files in core opt into happy-dom via // @vitest-environment happy-dom; the rest run under the default Node environment. Reworded in 90b4a88.
Four factual corrections flagged in the PR #236 review: - Code of Conduct: GitHub doesn't have DMs and issues in a public repo aren't confidential. Point at GitHub's abuse-reporting flow and the `author` email in `package.json` instead. - `pnpm coverage`: the configured provider in `packages/core/vite.config.ts` is `istanbul` (`@vitest/coverage-istanbul`), not V8. - lint-staged: `.lintstagedrc` only targets `*.css`, not `*.{html,css}`. - Vitest environment: `vite.config.ts` doesn't set a global `environment`. Tests default to Node and opt into happy-dom with a `// @vitest-environment happy-dom` directive per file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The initial
CONTRIBUTING.mdlanded in #193 (thanks @tewaris for spotting the gap!). Reading it against the current stack, almost every step would mislead a new contributor:npm install/npm run dev/npm test— the repo uses pnpm + Turborepo (pinned topnpm@10.22.0), and the dev surface ispnpm dev(a Turbo task that boots the examples Vite server).main— the base branch ismaster.commit-msghook enforces via commitlint. New contributors who follow the doc will get their first commit rejected.I-prefix rule for interfaces, the_-prefix rule for private members, thecomplexity ≤ 20cap, or the CI-enforcedpnpm check-circulargate.examples/dev surface, and thee2e/Playwright suite are not mentioned at all.This PR rewrites the doc to match what's actually enforced today, drawing from
README.md,CLAUDE.md,.commitlintrc.cjs,eslint.config.mjs, and the rootpackage.jsonscripts. Key additions:pnpm install(which also wires up husky).--filter @muyajs/coretest:spec, test:spec:commonmark, test:spec:gfm).ScrollPage.loadBlockreturnsundefinedfor unregistered blocks) and the "no newILinkReferenceDefinitionState" rule.expected-failures.json) andMIGRATION.mdupdates for public-API changes.Refs #193.
Test plan
package.jsonandpackages/core/package.jsonscripts (test:spec*,e2e:ui,coverageall exist;e2e/BACKLOG.mdande2e/README.mdexist).package.json(node >=18,pnpm >=8.5,packageManager: pnpm@10.22.0) and the changelog plugin pin documented inCLAUDE.md.gh api repos/marktext/muyareportshas_discussions: false)..commitlintrc.cjsverbatim.🤖 Generated with Claude Code