Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
255 lines (189 loc) · 7.05 KB

CONTRIBUTING.md

File metadata and controls

255 lines (189 loc) · 7.05 KB

Contributing

Contributions are welcome! We appreciate any help you can provide to improve the project. Please read our Code of Conduct before you start.

How to Contribute

  1. Fork the repository on GitHub.
  2. Clone your fork to your local machine.
  3. Create a new branch for your changes: git checkout -b my-feature-branch.
  4. Make your changes and commit them following our commit message format.
  5. Push your changes to your fork: git push origin my-feature-branch.
  6. Create a pull request from your fork to the main repository following our PR title format.

Commit Message Format

We follow the Conventional Commits specification for clear and semantic commit messages.

Format

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

[optional body]

[optional footer(s)]

Types

  • feat: A new feature for the user
  • fix: A bug fix
  • docs: Documentation changes only
  • style: Code style changes (formatting, semicolons, etc.) with no code logic change
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvements
  • test: Adding or updating tests
  • chore: Changes to build process, tools, dependencies, or other maintenance tasks
  • ci: Changes to CI/CD configuration files and scripts

Scope (optional but recommended)

The scope provides additional contextual information and is contained within parentheses:

  • agents: Changes to agent system (plugins, registry, core)
  • cli: CLI commands and interface
  • config: Configuration system
  • analytics: Analytics and tracking
  • workflows: CI/CD workflow management
  • auth: Authentication and SSO
  • proxy: Proxy server functionality
  • tools: Built-in agent tools (filesystem, git, etc.)
  • docs: Documentation updates

Rules

  • Description: Use imperative mood ("add" not "added" or "adds")
  • Capitalization: Start with lowercase letter
  • Length: First line max 72 characters, body lines max 100 characters
  • Body: Separate from description with blank line, wrap at 100 characters
  • Footer: Reference issues using Fixes #123 or Closes #456
  • Breaking Changes: Mark with BREAKING CHANGE: in footer or ! after type/scope

Examples

✅ Valid:

feat(analytics): add API response tracking for all agents

Implement comprehensive tracking of API requests and responses across
all agent types (Claude, Gemini, CodeMie Native).

Includes automatic content extraction from multiple API formats and
privacy-first redaction of sensitive data.

Closes #123

fix(config): resolve profile switching for legacy configs

Migration from v1 to v2 config format was not preserving
the active profile setting.

Fixes #456

docs: update README with new analytics commands

chore(deps): bump @langchain/core to v1.0.4

feat(cli)!: change default timeout from 30s to 60s

BREAKING CHANGE: The default API timeout has been increased from 30
seconds to 60 seconds to accommodate longer-running requests. Users
relying on the 30s timeout should explicitly set the timeout flag.

❌ Invalid:

Add analytics support              # Missing type
analytics: Add support             # Wrong type format
feat(analytics) add support        # Missing colon
feat(analytics): Added support     # Wrong mood (use "add" not "Added")
feat(analytics): Add Support       # Description should be lowercase
Feat(analytics): add support       # Type should be lowercase

Pull Request Format

PR titles must follow the same Conventional Commits format:

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

PR Guidelines

  • Title: Use Conventional Commits format (same as commits)
  • Description: Provide clear context about:
    • What: What changes were made
    • Why: Motivation and context
    • How: Approach and implementation details
    • Testing: How the changes were tested
  • References: Link related issues using Fixes #123, Closes #456, or Relates to #789
  • Breaking Changes: Clearly document any breaking changes in the PR description
  • Commits: Each commit in the PR should follow the commit message format

PR Description Template

## Summary
Brief overview of the changes

## Motivation
Why these changes are needed

## Changes
- Detailed list of changes
- One item per significant change

## Testing
How the changes were tested

## Breaking Changes
List any breaking changes (if applicable)

## Related Issues
Fixes #123
Relates to #456

Examples

✅ Valid PR Titles:

feat(analytics): add unified tracking system for all agents
fix(config): resolve multi-provider profile switching
docs: add contribution guidelines for commit messages
chore: update CI pipeline with validation checks

❌ Invalid PR Titles:

Add analytics                    # Missing type and scope
Analytics support                # Missing type format
feat: Add Analytics Support      # Description should be lowercase
feature(analytics): add support  # Use "feat" not "feature"

Setting up the Development Environment

To get the project running locally, follow these steps:

  1. Clone the repository: 
    git clone https://github.com/codemie-ai/codemie-code.git
cd codemie-code
  2. Install dependencies: 
    npm install
  3. Build the project: 
    npm run build
  4. Link the package to use the codemie command globally: 
    npm link

Running Tests and Validation

Run All Tests

npm test                # Run tests in watch mode
npm run test:run        # Run tests once
npm run test:unit       # Run unit tests only
npm run test:integration # Run integration tests only

Run Validation Checks

IMPORTANT: Before creating a pull request, run the full CI checks locally:

# Run full CI checks (commit validation + license + lint + build + tests)
npm run ci

# Run CI with secrets detection (requires Docker)
npm run ci:full

Note: npm run ci includes commit validation and will fail if your last commit doesn't follow the Conventional Commits format. This ensures you catch format issues before pushing.

Individual validation commands:

# Validate your last commit message
npm run commitlint:last

# Check for exposed secrets (requires Docker)
npm run validate:secrets

# Check dependency licenses
npm run license-check

# Run linting
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Build TypeScript
npm run build

Pre-Commit Checklist

Before committing, ensure:

  1. ✅ Commit message follows Conventional Commits format
  2. ✅ Code passes ESLint with zero warnings: npm run lint
  3. ✅ TypeScript compiles: npm run build
  4. ✅ All tests pass: npm run test:run
  5. ✅ No secrets exposed: npm run validate:secrets (optional, requires Docker)
  6. ✅ Dependencies have approved licenses: npm run license-check

Quick check: Run npm run ci to verify everything passes before pushing.