Skip to content

Contributing Guidelines

How to contribute to the Constellation project.

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Assume good intent
  • Report violations to team leads

Getting Started

  1. Read SETUP_GUIDE.md
  2. Read CODE_STYLE_GUIDE.md
  3. Read ARCHITECTURE.md
  4. Pick a task from the issue tracker

Development Workflow

1. Create Feature Branch

git checkout -b feature/description-of-feature
# or
git checkout -b fix/issue-description

Naming convention: feature/* or fix/*

2. Make Changes

  • Follow code style guide
  • Write tests for new features
  • Add comments for complex logic
  • Keep commits atomic

3. Run Quality Checks

# Format code
bun lint --fix

# Run tests
bun test:run

# Check coverage
bun test:coverage

Requirements: - ✅ All tests pass - ✅ No linting errors - ✅ TypeScript compiles - ✅ Code coverage > 80%

4. Commit

git commit -m "feat: add new feature"

Commit message format: 

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, test, chore

Examples: 

feat(editor): add rich text formatting
fix(auth): resolve token refresh issue
docs(setup): update environment variables
test(components): add Button component tests

5. Push and Create Pull Request

git push origin feature/description

Then create PR via GitHub UI.

Pull Request Process

PR Title

Format: [Type] Short description

Examples: 

[Feature] Add rich text editor
[Fix] Resolve authentication bug
[Docs] Update setup guide
[Refactor] Optimize performance

PR Description

Use this template:

## Description
Brief description of changes

## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Breaking change

## Testing
- [ ] Unit tests added
- [ ] Component tests added
- [ ] Manually tested
- [ ] No new tests needed

## Checklist
- [ ] Code follows style guide
- [ ] Tests pass
- [ ] ESLint passes
- [ ] TypeScript passes
- [ ] Documentation updated
- [ ] No console errors

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Related Issues
Closes #123

Code Review

  • Reviewers will provide feedback
  • Address feedback with new commits
  • Re-request review when ready
  • Squash commits before merge (if many)

Testing Requirements

New Features

// ✅ Required: Tests for new functionality
describe('NewFeature', () => {
  it('should do X', () => { });
  it('should do Y', () => { });
  it('should handle errors', () => { });
});

Bug Fixes

// ✅ Required: Test that verifies the fix
describe('BugFix', () => {
  it('should not crash when X happens', () => { });
});

Documentation

// ✅ Required: JSDoc comments for public APIs
/**
 * Description of function
 * @param param - Parameter description
 * @returns Return value description
 */
export function myFunction(param: string): void { }

Documentation

Update docs for:

  • ✅ New features
  • ✅ API changes
  • ✅ Configuration changes
  • ✅ Breaking changes

Documentation locations:

  • Feature overview → docs/[NUMBER]-FEATURE.md
  • API changes → docs/22-API_INTEGRATION.md
  • Setup changes → docs/02-SETUP_GUIDE.md
  • Examples → Comments in code

Performance Guidelines

Before Submitting PR

Run performance checks:

# Check bundle size
npm run build

# Check performance metrics
npm run build:analyze

Optimization Tips

  • Use React.memo for expensive components
  • Implement code splitting with dynamic imports
  • Optimize images with Next.js Image component
  • Use lazy loading for heavy components

Common Mistakes to Avoid

❌ Don't

  • ❌ Commit directly to main
  • ❌ Ignore failing tests
  • ❌ Skip the code style check
  • ❌ Make unrelated changes
  • ❌ Leave console.log statements
  • ❌ Use any types
  • ❌ Hardcode values
  • ❌ Make large PRs (> 500 lines)

✅ Do

  • ✅ Create feature branches
  • ✅ Ensure all tests pass
  • ✅ Follow code style guide
  • ✅ Keep PRs focused
  • ✅ Remove debug statements
  • ✅ Use proper types
  • ✅ Use constants/config
  • ✅ Break large changes into smaller PRs

Commit Message Examples

Feature

feat(editor): add table insertion plugin

Add support for inserting tables into documents using the editor toolbar.
Includes basic styling and cell editing capabilities.

Bug Fix

fix(auth): resolve token refresh on expiry

Token was not being refreshed when expired, causing authentication
failures. Now uses automatic refresh mechanism before expiry.

Fixes #456

Documentation

docs(api): add API integration guide

Document how to create services and communicate with backend API.
Includes examples for GET, POST, PUT, DELETE requests.

Refactor

refactor(components): extract common button logic

Extract repeated button styles and behavior into reusable component.
Reduces code duplication and improves maintainability.

Review Checklist

For Code Reviewers

  • [ ] Code follows style guide
  • [ ] Logic is correct and efficient
  • [ ] Tests are comprehensive
  • [ ] No security vulnerabilities
  • [ ] Documentation is updated
  • [ ] Performance is acceptable
  • [ ] No console.log or debug code
  • [ ] Types are properly used

For PR Author

  • [ ] Tests pass locally
  • [ ] ESLint passes
  • [ ] TypeScript compiles
  • [ ] No breaking changes
  • [ ] Documentation updated
  • [ ] Commits are clean
  • [ ] PR description is clear

Issue Reporting

Before Creating Issue

  1. Search existing issues
  2. Check if it's documented
  3. Try reproducing locally

Issue Template

## Description
Clear description of the issue

## Steps to Reproduce
1. Do X
2. Do Y
3. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: macOS / Windows / Linux
- Node: version
- Browser: Chrome / Firefox / Safari

## Screenshots
[If applicable]

## Additional Context
[Any other context]

Release Process

Version Numbering

Use Semantic Versioning: MAJOR.MINOR.PATCH

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes

Example: 0.1.0 → 0.2.0 (new features)

Release Checklist

  • [ ] All PRs merged
  • [ ] Tests pass
  • [ ] Docs updated
  • [ ] Version number updated
  • [ ] Changelog updated
  • [ ] Build succeeds
  • [ ] Deployed to staging
  • [ ] Tested in staging
  • [ ] Tagged in git
  • [ ] Deployed to production

Getting Help

  • Questions: Ask in team chat or create discussion
  • Bugs: Create issue with bug template
  • Ideas: Create discussion with proposal
  • Code Review: Request review from maintainers

Recognition

Contributors will be: - Added to CONTRIBUTORS.md - Mentioned in release notes - Featured in project documentation

Last Updated: January 2026
Questions? Ask in team chat or create a discussion on GitHub