Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides comprehensive instructions for contributing to the BMSview project. It covers the development workflow, coding standards, and processes for both human developers and AI coding agents like GitHub Copilot. The goal is to maintain a clean, consistent, and high-quality codebase.
The project has a strong emphasis on collaboration with AI agents, with specific instructions and configurations in place to facilitate AI-driven development. This includes detailed issue creation guidelines and a well-defined review process for AI-generated pull requests. For more details on the system architecture, refer to the System Architecture and AI Integration documentation.
Sources: CONTRIBUTING.md:3-4, GEMINI.md:50-54
Getting Started
Before contributing, you must set up your local development environment. This involves cloning the repository, installing dependencies, and configuring environment variables.
Sources: CONTRIBUTING.md:20-22
Prerequisites
- Node.js 20+
- npm or yarn
- A MongoDB instance (local or cloud)
- A Google Gemini API key
Sources: CONTRIBUTING.md:25-28
Local Setup Workflow
The following diagram illustrates the steps to get the development server running locally.
This diagram shows the sequence of commands and configuration steps needed to set up the local development environment.
Sources: CONTRIBUTING.md:30-49, README.md:50-60
Development Workflow
The project uses a feature-branch workflow. All changes are made in a branch and then merged into main via a Pull Request.
Sources: CONTRIBUTING.md:53-56
For Human Contributors
The standard workflow for human developers involves creating a branch, making changes, testing, and opening a pull request.
This flowchart outlines the development and validation cycle for human contributors. A successful build (npm run build) is a mandatory requirement before a PR can be merged.
Sources: CONTRIBUTING.md:58-91, GEMINI.md:50-54
Conventional Commits
Commit messages must follow the Conventional Commits specification. This helps in automating changelogs and understanding the nature of changes at a glance.
| Prefix | Description |
|---|---|
feat: | A new feature |
fix: | A bug fix |
docs: | Documentation changes |
test: | Adding or fixing tests |
refactor: | Code refactoring |
chore: | Maintenance tasks |
Sources: CONTRIBUTING.md:83-90
For AI Coding Agents (GitHub Copilot)
The repository is specifically configured to work with AI coding agents. This includes detailed instructions, configuration files, and guidelines for creating AI-friendly issues.
- Primary Instructions:
.github/copilot-instructions.md - Configuration:
.copilot/config.json - Additional Context:
CODEBASE_PATTERNS_AND_BEST_PRACTICES.md
Sources: CONTRIBUTING.md:95-99, README.md:163-166
Creating Issues for AI
Well-defined issues are critical for successful AI collaboration. Issues should be clear, scoped, and provide sufficient context.
Good Issue Example:
Title: Fix duplicate analysis detection for identical BMS screenshots
Description:
Currently, when a user uploads the same BMS screenshot twice, they don't receive
a duplicate warning. The SHA-256 hash comparison should flag identical images.
Acceptance Criteria:
- Upload same screenshot twice
- Second upload shows isDuplicate flag
- User sees clear warning message
Files to Modify:
- netlify/functions/utils/analysis-pipeline.cjs
- services/geminiService.ts
- components/AnalysisResult.tsx
Bad Issue Example:
Title: Fix the duplicate thing
Description:
Duplicates don't work correctly. Please fix.
Sources: CONTRIBUTING.md:103-134, ISSUE_CREATION_GUIDE.md
Ideal Tasks for AI vs. Human Review
| Ideal Tasks for AI Agents | Tasks Requiring Human Review |
|---|---|
| Bug fixes with clear reproduction steps | Major architecture changes |
| Unit test additions | Security-critical code (auth, encryption) |
| Documentation updates | Performance optimization |
| Code refactoring (e.g., extract functions) | Breaking API changes |
| Well-scoped feature additions | Complex business logic |
| Dependency updates | |
| Linting and code style fixes |
Sources: CONTRIBUTING.md:136-154, README.md:176-184
Issue Creation Process
The project provides multiple methods for creating issues, particularly for the AI Feedback System, to streamline development.
This diagram shows the different paths to creating a structured GitHub issue within the project.
Sources: ISSUE_CREATION_GUIDE.md:5-39, AI_FEEDBACK_SYSTEM_ISSUES.md
Pull Request (PR) Process
All PRs are subject to a strict review process to ensure code quality and stability. A build failure will block a PR from being merged.
This diagram shows the lifecycle of a pull request from creation to merge.
PR Review Checklist
All items on this checklist must be completed before a PR can be merged.
- Code builds without errors (
npm run buildsucceeds) - MANDATORY - All tests pass
- Linting passes
- Documentation updated
- No sensitive data or secrets committed
- Changes are minimal and focused
- No
console.logstatements in production code
Sources: CONTRIBUTING.md:164-180
Testing Guidelines
The project follows a policy of testing against real services (Gemini API, MongoDB) to ensure production parity. Mocks are strictly prohibited.
- Run all tests:
npm test - Run tests in watch mode:
npm run test:watch - Generate coverage report:
npm run test:coverage
Tests are located in the tests/ directory and use the .test.js extension. External dependencies like the Gemini API and MongoDB should be targeted by the tests, not mocked.
Sources: CONTRIBUTING.md:184-213, TESTING.md:3-8
Coding Standards & Project Structure
The project enforces different standards for frontend and backend code due to the use of different module systems.
Module Systems
- Frontend (
.ts/.tsx): Use ES Modules (import/export). - Backend (
.cjs): Use CommonJS (require/module.exports). - Critical: Never mix module systems.
Sources: CODEBASE.md:8-12, GEMINI.md:41-44
File Organization
The repository is organized into distinct directories for different parts of the application.
This diagram visualizes the main directories and their purpose within the project structure.
Sources: CONTRIBUTING.md:238-248, README.md:71-84
Frontend (React/TypeScript)
- Components: Use PascalCase for functional components with hooks.
- State Management: Global state is managed via React's Context API with
useReducer, located instate/appState.tsx. - Styling: Use Tailwind CSS classes.
- Imports: Use path aliases (e.g.,
components/*,services/*) for cleaner imports.
Sources: CONTRIBUTING.md:217-222, GEMINI.md:46-49
Backend (Netlify Functions)
- Files: Use the
.cjsextension for CommonJS modules. - Logging: Use the structured logger from
utils/logger.cjs. - Errors: Use the
errorResponse()helper fromutils/errors.cjs. - Database: Interact with MongoDB via the
getCollection()helper.
Sources: CONTRIBUTING.md:225-231, CODEBASE.md:14-20