Contributing to Seed

Thank you for your interest in contributing to Seed! This guide will help you get started with contributing code, documentation, and ideas to the project.

Code of Conduct

Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for everyone.

Ways to Contribute

1. Report Issues

Found a bug or have a feature request?

Check existing issues first
Create a new issue with:
- Clear title: Descriptive and concise
- Reproduction steps: How to reproduce the problem
- Expected behavior: What should happen
- Actual behavior: What actually happens
- Environment: OS, Node version, configuration
- Logs: Relevant error messages or stack traces

Example issue title:

Good: "OAuth token endpoint returns 500 when Redis is unavailable"
Bad: "Token endpoint broken"

2. Submit Code

Ready to write code?

Small changes (typo fixes, documentation):

Fork the repository
Make your changes
Submit a merge request

Larger changes (new features, refactoring):

Open an issue first to discuss the approach
Get feedback from maintainers
Implement the agreed-upon solution
Submit a merge request

3. Improve Documentation

Documentation is crucial! You can help by:

Fixing typos or unclear explanations
Adding examples or code snippets
Writing tutorials or guides
Improving API documentation

4. Test and Review

Help maintain quality by:

Testing merge requests
Reviewing code changes
Reporting bugs you find
Suggesting improvements

Getting Started

1. Fork and Clone

bash

# Fork the repository on GitLab first, then:
git clone git@gitlab.byterecursion.com:YOUR_USERNAME/seed.git
cd seed

# Add upstream remote
git remote add upstream git@gitlab.byterecursion.com:mcp-servers/seed.git

2. Set Up Development Environment

bash

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Start development server
npm run dev

See Development Setup for detailed instructions.

3. Create a Branch

Use descriptive branch names following this pattern:

bash

# New feature
git checkout -b feature/add-user-authentication

# Bug fix
git checkout -b fix/redis-connection-error

# Documentation
git checkout -b docs/update-api-reference

# Refactoring
git checkout -b refactor/simplify-auth-middleware

Development Workflow

1. Write Code

Follow our coding standards:

TypeScript strict mode: No any types
ES Modules: Use .js extensions in imports
Code style: Prettier formats automatically
Linting: ESLint catches errors

See Code Quality for details.

2. Write Tests

All code changes require tests:

Unit tests for new functions
Integration tests for new endpoints
Edge cases and error conditions
Aim for 80%+ coverage

See Testing Guide for patterns.

3. Run Validation

Before committing, run:

bash

npm run validate

This runs:

Prettier formatting
ESLint linting
TypeScript type checking
Full test suite with coverage

Fix any errors before proceeding.

4. Commit Changes

Write clear, conventional commit messages:

Format:

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

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

bash

# Good
git commit -m "feat(auth): add JWT token refresh support"
git commit -m "fix(oauth): handle expired authorization codes"
git commit -m "docs(api): add examples for OAuth endpoints"

# Bad
git commit -m "fixed stuff"
git commit -m "Update file.ts"

Detailed commit:

bash

git commit -m "feat(mcp): add database query tool

Implements a new MCP tool for querying Redis client data.
Supports field filtering and requires authentication.

Closes #42"

5. Push Changes

bash

git push origin feature/my-feature

6. Create Merge Request

Go to your fork on GitLab
Click "Create merge request"
Fill out the template:
- Title: Clear, descriptive
- Description: What changed and why
- Related issues: Link to issues
- Testing: How you tested it

Merge request template:

markdown

## Summary
Brief description of what this MR does.

## Changes
- Added X feature
- Fixed Y bug
- Refactored Z component

## Testing
- [ ] Unit tests passing
- [ ] Integration tests passing
- [ ] Manual testing completed
- [ ] Documentation updated

## Related Issues
Closes #123

Code Review Process

What to Expect

Automated checks: CI/CD runs tests and validation
Maintainer review: Code review from a maintainer
Feedback: Requests for changes or questions
Approval: Once changes are approved
Merge: Maintainer merges your MR

Responding to Feedback

Be responsive to review comments
Ask questions if something is unclear
Make requested changes promptly
Push updates to the same branch
Resolve conversations when addressed

Review Guidelines for Contributors

When reviewing others' code:

Check for:

Correctness: Does it work as intended?
Tests: Are there adequate tests?
Code quality: Follows project standards?
Documentation: Clear and updated?
Security: No vulnerabilities?

Provide:

Constructive feedback
Specific suggestions
Code examples where helpful
Appreciation for good work

Coding Standards

TypeScript

Strict mode: Always enabled
No any: Use unknown and type guards
Explicit types: On function parameters and returns
Import types: Use import type for types

typescript

// Good
import type { Request, Response } from "express";

export function handler(req: Request, res: Response): void {
  // ...
}

// Bad
import { Request } from "express";

export function handler(req, res) {
  // ...
}

Naming Conventions

Variables/functions: camelCase
Classes/interfaces: PascalCase
Constants: UPPER_SNAKE_CASE
Files: kebab-case
MCP tools: snake_case

Error Handling

Always handle errors:

typescript

// Good
try {
  const result = await operation();
  return result;
} catch (error) {
  console.error("Operation failed:", error);
  throw new Error(`Failed: ${error.message}`);
}

// Bad
const result = await operation(); // Unhandled promise

Security Guidelines

Never Commit

Secrets: API keys, tokens, passwords
Credentials: Database URLs with passwords
Private keys: JWT signing keys, SSL certificates
Environment files: Real .env files

Security Best Practices

Validate all user input
Use parameterized queries
Escape output in error messages
Implement rate limiting
Use secure defaults
Follow OWASP guidelines

Reporting Security Issues

Do not open public issues for security vulnerabilities.

Instead:

Email the maintainers privately
Provide detailed reproduction steps
Suggest a fix if possible
Allow time for a patch before disclosure

Getting Help

Questions

Technical questions: Open an issue with question label
Documentation: Check the wiki

Learning Resources

Recognition

Contributors are recognized in:

Release notes
Project README

Thank you for contributing to Seed!

Development Setup - Set up your environment
Testing Guide - Write effective tests
Code Quality - Follow coding standards
Adding MCP Tools - Create MCP tools

Contributing to Seed ​

Code of Conduct ​

Ways to Contribute ​

1. Report Issues ​

2. Submit Code ​

3. Improve Documentation ​

4. Test and Review ​

Getting Started ​

1. Fork and Clone ​

2. Set Up Development Environment ​

3. Create a Branch ​

Development Workflow ​

1. Write Code ​

2. Write Tests ​

3. Run Validation ​

4. Commit Changes ​

5. Push Changes ​

6. Create Merge Request ​

Code Review Process ​

What to Expect ​

Responding to Feedback ​

Review Guidelines for Contributors ​

Coding Standards ​

TypeScript ​

Naming Conventions ​

Error Handling ​

Security Guidelines ​

Never Commit ​

Security Best Practices ​

Reporting Security Issues ​

Getting Help ​

Questions ​

Learning Resources ​

Recognition ​

Related Documentation ​

Contributing to Seed

Code of Conduct

Ways to Contribute

1. Report Issues

2. Submit Code

3. Improve Documentation

4. Test and Review

Getting Started

1. Fork and Clone

2. Set Up Development Environment

3. Create a Branch

Development Workflow

1. Write Code

2. Write Tests

3. Run Validation

4. Commit Changes

5. Push Changes

6. Create Merge Request

Code Review Process

What to Expect

Responding to Feedback

Review Guidelines for Contributors

Coding Standards

TypeScript

Naming Conventions

Error Handling

Security Guidelines

Never Commit

Security Best Practices

Reporting Security Issues

Getting Help

Questions

Learning Resources

Recognition

Related Documentation