docs: add Contributing guide #948
Conversation
Add a comprehensive Contributing guide (CONTRIBUTING.md) with: - Mandatory communication requirements before starting work - Detailed issue reporting guidelines with templates - Complete development setup and workflow instructions - Code quality standards and testing requirements - Pull Request process with Conventional Commits guidelines Polish existing documentation: - Improve CONTRIBUTING.md formatting and clarity - Reorganize README.md Development section with quick command reference - Add contributing page in website docs pointing to the guide The guide emphasizes the importance of communication with maintainers before starting work to maximize the chances of contribution acceptance and prevent wasted effort.
WalkthroughAdds a root-level CONTRIBUTING.md with detailed contributor guidelines, updates README.md to refer to the new contributing guide and simplify development instructions, and adds a website docs page at Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
CONTRIBUTING.md (1)
5-5: Minor wording improvement: Strengthen directive language.Line 5 uses "make sure you are welcoming" — consider using "ensure you are welcoming" for more direct, assertive phrasing that better matches the formal tone of the rest of the document.
-All members of our community are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). Please make sure you are welcoming and friendly in all of our spaces. +All members of our community are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). Please ensure you are welcoming and friendly in all of our spaces.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
CONTRIBUTING.md(1 hunks)README.md(2 hunks)packages/website/docs/development/contributing.md(1 hunks)
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 849
File: packages/html/stories/DragSource.stories.js:98-101
Timestamp: 2025-06-13T07:48:10.300Z
Learning: User tbouffard prefers answers in English; avoid switching to other languages in future replies.
📚 Learning: 2025-01-28T16:22:25.804Z
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 593
File: .github/workflows/create-github-release.yml:42-42
Timestamp: 2025-01-28T16:22:25.804Z
Learning: In the GitHub release notes template for maxGraph, TODO comments are intentionally included to mark sections that must be reviewed by maintainers before publishing the release. These TODOs should not be removed or converted to validation steps as they are part of the release review process.
Applied to files:
packages/website/docs/development/contributing.mdCONTRIBUTING.mdREADME.md
📚 Learning: 2025-05-13T12:54:55.231Z
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 826
File: packages/js-example-nodejs/src/index.cjs:64-69
Timestamp: 2025-05-13T12:54:55.231Z
Learning: For example code in the maxGraph repository, maintainers prefer to keep scripts simple without error handling to focus on demonstrating core functionality, especially in demonstration scripts like those in packages/js-example-nodejs.
Applied to files:
README.md
📚 Learning: 2025-04-29T13:25:31.494Z
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 791
File: packages/ts-example/vite.config.js:30-30
Timestamp: 2025-04-29T13:25:31.494Z
Learning: In the maxGraph project, each example package (ts-example, ts-example-selected-features, ts-example-without-defaults) implements different use cases with varying features, resulting in different application sizes. Therefore, each package has its own specific chunkSizeWarningLimit value in its vite.config.js file, calibrated to its expected bundle size.
Applied to files:
README.md
📚 Learning: 2025-04-22T16:34:40.309Z
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 774
File: packages/ts-example-selected-features/package.json:11-13
Timestamp: 2025-04-22T16:34:40.309Z
Learning: In the maxGraph project, TypeScript is defined as a dependency in the root package.json (~5.8.2) and not in individual package.json files for example packages. The build scripts in example packages can use `tsc` commands because the TypeScript dependency is hoisted in the monorepo structure.
Applied to files:
README.md
📚 Learning: 2025-04-22T16:34:40.309Z
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 774
File: packages/ts-example-selected-features/package.json:11-13
Timestamp: 2025-04-22T16:34:40.309Z
Learning: In the maxGraph project, TypeScript is defined as a dependency in the root package.json and not in individual package.json files for example packages. The build scripts in example packages can use `tsc` because it's available through this hoisted dependency in the monorepo structure.
Applied to files:
README.md
🪛 LanguageTool
packages/website/docs/development/contributing.md
[style] ~7-~7: The wording of this phrase can be improved.
Context: ...e community and appreciate your help in making this project better. For comprehensive information about c...
(MAKE_STYLE_BETTER)
CONTRIBUTING.md
[style] ~3-~3: The wording of this phrase can be improved.
Context: ...e community and appreciate your help in making this project better. All members of our community are expe...
(MAKE_STYLE_BETTER)
[style] ~5-~5: Consider using a different verb to strengthen your wording.
Context: ...of Conduct](CODE_OF_CONDUCT.md). Please make sure you are welcoming and friendly in all o...
(MAKE_SURE_ENSURE)
[uncategorized] ~316-~316: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...s free series: [How to Contribute to an Open Source Project on GitHub](https://egghead.io/s...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build
🔇 Additional comments (8)
packages/website/docs/development/contributing.md (1)
1-24: Well-structured website documentation entry point.The file effectively serves as a website-facing overview, directing visitors to the comprehensive CONTRIBUTING.md while providing convenient quick links to key resources. Front matter and content are clear and well-organized.
CONTRIBUTING.md (4)
16-40: Excellent emphasis on mandatory pre-work communication.The "Before You Start" section effectively establishes clear expectations and prevents wasted effort. The four-step process (find/create issue → comment → wait for assignment → understand scope) is well-justified with explicit benefits, and the warning about potential rejection for non-compliant PRs is appropriately direct.
53-94: Strong issue reporting standards with clear consequences.The issue reporting guidance emphasizes completeness with concrete examples of required environment details. The warning that incomplete reports will be rejected and requesters must resubmit is appropriately firm and should discourage low-effort reports.
106-228: Comprehensive development setup and guidelines.Development prerequisites, setup steps, common commands, and development guidelines are well-organized. Commands reference workspace syntax (
-w) appropriately and align with monorepo structure. Testing and code quality standards are explicit and helpful.
230-316: Clear pull request process with Conventional Commits guidance.The PR checklist, Conventional Commits format, and scope/type guidance are well-structured. Examples are practical (e.g.,
feat: add annotation support for cells) and the emphasis on PR title becoming the commit message clarifies why precision matters. The link to external tutorial ("How to Contribute to an Open Source Project on GitHub") is helpful for first-time contributors.README.md (3)
204-210: Clean reorganization directing contributors to comprehensive guide.Moving detailed setup and workflow instructions to CONTRIBUTING.md while keeping README focused on high-level overview is a sound information architecture choice. Links to the contributing guide, CLAUDE.md, and release documentation provide clear pathways for contributors at different expertise levels.
212-229: Practical Quick Command Reference improves developer experience.The command reference covers essential workflows (setup, development, building, testing) with correct npm workspace syntax. Organizing commands by task category and including the note about running dev commands in parallel enhances usability. Commands align with the comprehensive guidance in CONTRIBUTING.md.
233-249: Clear npm package building instructions and integration guidance.The section appropriately distinguishes between published npm packages and local builds, explaining both
npm packandnpm linkworkflows. Reference to maxgraph-integration-examples repository provides practical next steps for developers.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CONTRIBUTING.md(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 857
File: packages/core/src/view/plugins/SelectionHandler.ts:1081-1092
Timestamp: 2025-06-26T13:27:19.012Z
Learning: User tbouffard prefers to keep PRs focused on their main objective and defer implementation improvements or logic fixes to future dedicated PRs. For maxGraph, refactoring PRs like Dictionary→Map migration should not include unrelated logic improvements even when valid issues are identified in the migrated code.
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 849
File: packages/html/stories/DragSource.stories.js:98-101
Timestamp: 2025-06-13T07:48:10.300Z
Learning: User tbouffard prefers answers in English; avoid switching to other languages in future replies.
📚 Learning: 2025-01-28T16:22:25.804Z
Learnt from: tbouffard
Repo: maxGraph/maxGraph PR: 593
File: .github/workflows/create-github-release.yml:42-42
Timestamp: 2025-01-28T16:22:25.804Z
Learning: In the GitHub release notes template for maxGraph, TODO comments are intentionally included to mark sections that must be reviewed by maintainers before publishing the release. These TODOs should not be removed or converted to validation steps as they are part of the release review process.
Applied to files:
CONTRIBUTING.md
🪛 LanguageTool
CONTRIBUTING.md
[style] ~3-~3: The wording of this phrase can be improved.
Context: ...e community and appreciate your help in making this project better. All members of our community are expe...
(MAKE_STYLE_BETTER)
[uncategorized] ~316-~316: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...s free series: [How to Contribute to an Open Source Project on GitHub](https://egghead.io/s...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.18.1)
CONTRIBUTING.md
267-267: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build
🔇 Additional comments (2)
CONTRIBUTING.md (2)
130-141: Consider clarifying branch naming scope for maintainer vs. forked repositories.The branch naming conventions are clearly documented, but the past review feedback suggests distinguishing between branches created directly by maintainers (where this is required for organization) versus forked repository branches (where this is helpful but not mandatory). This would help clarify expectations for different contributor scenarios.
Consider adding a note like:
Branch naming convention: - `feat/ISSUE_NUMBER-short-description` - For new features - `fix/ISSUE_NUMBER-short-description` - For bug fixes - `docs/ISSUE_NUMBER-short-description` - For documentation - `refactor/ISSUE_NUMBER-short-description` - For refactoring Example: `feat/25-annotations_to_tasks` or `fix/42-edge-rendering-safari` + + **Note:** This naming convention is required for branches created directly in the repository by maintainers to keep the workspace organized. For branches in forked repositories, following this guideline is helpful but not mandatory.
1-328: Comprehensive and well-structured contributing guide.This is an excellent, thorough contribution guide that covers all essential aspects: mandatory pre-work communication (a strong emphasis), issue templates, detailed development setup, clear commit conventions, and comprehensive PR requirements. The structure is logical, sections are well-organized, and the tone is appropriately encouraging while setting clear expectations. The emphasis on discussing with maintainers before investing time is particularly valuable for the community.
|
Add a comprehensive Contributing guide (CONTRIBUTING.md) with:
Polish existing documentation:
The guide emphasizes the importance of communication with maintainers
before starting work to maximize the chances of contribution acceptance
and prevent wasted effort.
Summary by CodeRabbit