Contributing to Mega Brain

Guidelines for contributing to the Mega Brain project, including branch workflow, commit conventions, and pull request process.

Maintainer

This project is maintained exclusively by @thiagofinch. All official updates and releases are published by the maintainer only.

Branch Workflow

IMPORTANT: Push direto em main = PROIBIDO. Always create a branch and open a Pull Request.

Branch Naming Convention

Use the following prefixes for your branch names:

Prefix	Use Case
feat/	New features
fix/	Bug fixes
docs/	Documentation changes
refactor/	Code refactoring
test/	Adding or updating tests

Format: {prefix}{short-description}

Examples

• feat/add-pipeline-v2
• fix/batch-log-format
• docs/update-readme
• refactor/simplify-session-logic

Commit Conventions

Mega Brain uses Conventional Commits for all commit messages:

feat: add new pipeline processor
fix: correct batch numbering in logs
docs: update CLAUDE.md with new rules
refactor: simplify session autosave logic
test: add unit tests for source-sync
chore: update dependencies

Reference related issues when applicable: feat: add login form refs #42

Commit Message Structure

<type>: <short description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Test additions or updates
• chore: Maintenance tasks
• perf: Performance improvements
• ci: CI/CD changes

Pull Requests

PR Workflow

1. Create a branch from main following the naming convention above
2. Make your changes with conventional commits
3. Open a PR using the provided template
4. Get approval - All PRs require approval from @thiagofinch before merge
5. Address checklist - Ensure all checklist items in the PR template are addressed
6. Link issues - Use Fixes #XX in the PR body to auto-close related issues

Before Opening PR

• Branch follows naming convention
• Commits follow conventional format
• All tests pass locally
• Documentation updated if needed

In PR Description

• Clear description of changes
• Link to related issues
• Screenshots/examples if UI changes
• Checklist items addressed

What NOT to Do

Prohibited Actions:

• Do NOT push directly to main
• Do NOT merge without PR approval
• Do NOT commit secrets, API keys, or .env files
• Do NOT skip the PR template checklist

Security Guidelines

Security Best Practices:

• Never hardcode credentials in code
• Use .env for all secrets (already in .gitignore)
• If a key is accidentally exposed, rotate it immediately
• Review code for sensitive information before committing

Secret Management

All sensitive configuration belongs in .env:

# .env (gitignored)
OPENAI_API_KEY=sk-...
VOYAGE_API_KEY=pa-...
GOOGLE_CLIENT_ID=...

Never commit:

• API keys or tokens
• Password or credentials
• .env files
• Private configuration data

Code Style

Naming Conventions

Type	Convention	Example
Folders	lowercase	inbox, system
Config files	SCREAMING-CASE	STATE.json, MEMORY.md
Python scripts	snake_case	session_start.py
Skills	kebab-case	knowledge-extraction/

Python Guidelines

• Use pathlib.Path for cross-platform file paths
• Python 3.10+ required
• Stdlib + PyYAML only for hooks
• Follow PEP 8 style guide

File Structure

from pathlib import Path

# Good - cross-platform
path = Path("inbox") / "file.txt"

# Bad - platform-specific
path = "inbox/file.txt"

Testing

Before submitting your PR:

# Validate layer distribution
npm run validate:layers

# Run full pre-publish checks
node bin/pre-publish-gate.js

Questions?

Open an issue or reach out to @thiagofinch on the project repository.

Need Help?

If you’re unsure about any contribution guidelines or have questions about implementation details, don’t hesitate to ask by opening an issue or contacting the maintainer.