Contributing to Dataproc MCP Server 🤝

Thank you for your interest in contributing to the Dataproc MCP Server! This document provides guidelines and information for contributors.

Code of Conduct
Getting Started
Development Setup
Contributing Guidelines
Pull Request Process
Issue Reporting
Development Workflow
Testing Requirements
Documentation Standards
Release Process

Code of Conduct

This project adheres to a code of conduct that we expect all contributors to follow:

Our Pledge

We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Positive behavior includes:

Using welcoming and inclusive language
Being respectful of differing viewpoints and experiences
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members

Unacceptable behavior includes:

Harassment, trolling, or discriminatory comments
Publishing others' private information without permission
Other conduct which could reasonably be considered inappropriate

Getting Started

Prerequisites

Node.js 18.0.0 or higher
npm 8.0.0 or higher
Git for version control
Google Cloud SDK (optional, for testing)

Fork and Clone

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/dataproc-mcp.git
cd dataproc-mcp

Add the upstream repository:

git remote add upstream https://github.com/dipseth/dataproc-mcp.git

Development Setup

Initial Setup

# Install dependencies
npm install

# Run setup script
npm run setup

# Build the project
npm run build

# Validate configuration
npm run validate

Development Environment

# Start development mode with watch
npm run dev

# Run in development mode
npm run start

# Run with inspector for debugging
npm run inspector

Environment Configuration

Create a .env file for local development:

# .env (not committed to git)
DATAPROC_PROJECT_ID=your-dev-project
DATAPROC_REGION=us-central1
GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service-account.json
NODE_ENV=development

Contributing Guidelines

Types of Contributions

We welcome several types of contributions:

Bug Reports - Help us identify and fix issues
Feature Requests - Suggest new functionality
Code Contributions - Implement features or fix bugs
Documentation - Improve guides, examples, and API docs
Testing - Add test cases or improve test coverage
Performance - Optimize existing functionality

Contribution Areas

High Priority:

Authentication method improvements
Performance optimizations
Additional cluster configuration options
Enhanced error handling and recovery
Cross-platform compatibility

Medium Priority:

Additional MCP tools for Dataproc operations
Integration with other Google Cloud services
Enhanced monitoring and logging
UI/UX improvements for documentation

Low Priority:

Code style improvements
Refactoring for maintainability
Additional examples and tutorials

Pull Request Process

Before Submitting

Check existing issues - Ensure your contribution isn't already being worked on
Create an issue - For significant changes, create an issue first to discuss
Follow conventions - Use conventional commit messages
Test thoroughly - Ensure all tests pass and add new tests as needed

PR Requirements

Code Quality:

All tests pass (npm run test:all-enhanced)
Code follows TypeScript best practices
No linting errors (npm run lint:check)
Proper formatting (npm run format:check)
Type checking passes (npm run type-check)

Documentation:

Code is properly documented with JSDoc comments
README updated if needed
API documentation updated for new features
Examples provided for new functionality

Testing:

Unit tests for new functionality
Integration tests for complex features
Performance tests for optimization changes
Manual testing completed

Commit Message Format

Use Conventional Commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
perf: Performance improvements
test: Adding or updating tests
build: Build system changes
ci: CI/CD changes
chore: Maintenance tasks

Examples:

feat(auth): add support for workload identity federation
fix(cluster): resolve timeout issue in cluster creation
docs(api): update authentication examples
perf(validation): optimize schema validation performance
test(integration): add multi-environment validation tests

PR Template

When creating a PR, use this template:

## Description
Brief description of changes and motivation.

## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Test improvement

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Performance impact assessed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] No breaking changes (or properly documented)

## Screenshots/Examples
If applicable, add screenshots or code examples.

## Related Issues
Closes #(issue number)

Issue Reporting

Bug Reports

Use the bug report template:

**Bug Description**
Clear description of the bug.

**To Reproduce**
Steps to reproduce the behavior:
1. Configure with '...'
2. Run command '...'
3. See error

**Expected Behavior**
What you expected to happen.

**Environment**
- OS: [e.g., macOS 12.0]
- Node.js version: [e.g., 18.17.0]
- Package version: [e.g., 1.2.3]
- Google Cloud SDK version: [if applicable]

**Additional Context**
Any other context about the problem.

**Logs**

Paste relevant logs here

Feature Requests

Use the feature request template:

**Feature Description**
Clear description of the feature you'd like to see.

**Use Case**
Describe the use case and why this feature would be valuable.

**Proposed Solution**
Describe how you envision this feature working.

**Alternatives Considered**
Any alternative solutions or features you've considered.

**Additional Context**
Any other context or screenshots about the feature request.

Development Workflow

Branch Strategy

main - Production-ready code
develop - Integration branch for features
feature/* - Feature development branches
fix/* - Bug fix branches
release/* - Release preparation branches

Workflow Steps

Create Feature Branch

git checkout develop
git pull upstream develop
git checkout -b feature/your-feature-name

Develop and Test

# Make changes
npm run build
npm run test:all-enhanced
npm run validate

Commit Changes

git add .
git commit -m "feat(scope): add new feature"

Push and Create PR

git push origin feature/your-feature-name
# Create PR on GitHub

Address Review Feedback

# Make requested changes
git add .
git commit -m "fix(scope): address review feedback"
git push origin feature/your-feature-name

Testing Requirements

Test Categories

Unit Tests (Required for all code changes)

npm run test:unit

Integration Tests (Required for API changes)

npm run test:integration
npm run test:auth

End-to-End Tests (Required for workflow changes)

npm run test:e2e

Performance Tests (Required for performance changes)

npm run test:performance

Coverage Requirements

Minimum coverage: 90% for new code
Critical paths: 100% coverage required
Performance: No regression in benchmarks

Writing Tests

Unit Test Example:

describe('Schema Validation', () => {
  it('should validate cluster configuration', () => {
    const config = {
      clusterName: 'test-cluster',
      projectId: 'test-project',
      region: 'us-central1'
    };
    
    const result = StartDataprocClusterSchema.safeParse(config);
    expect(result.success).toBe(true);
  });
});

Integration Test Example:

await runner.runTest('Authentication Test', async () => {
  const result = await validateServiceAccount(mockCredentials);
  assert(result.isValid, 'Service account should be valid');
});

Documentation Standards

Code Documentation

JSDoc Comments:

/**
 * Creates a new Dataproc cluster with the specified configuration.
 * 
 * @param config - Cluster configuration object
 * @param options - Additional options for cluster creation
 * @returns Promise that resolves to cluster creation result
 * @throws {ValidationError} When configuration is invalid
 * @throws {AuthenticationError} When credentials are invalid
 * 
 * @example
 * ```typescript
 * const result = await createCluster({
 *   clusterName: 'my-cluster',
 *   projectId: 'my-project',
 *   region: 'us-central1'
 * });
 * ```
 */
async function createCluster(config: ClusterConfig, options?: CreateOptions): Promise<ClusterResult> {
  // Implementation
}

API Documentation

Update docs/API_REFERENCE.md for new tools
Include practical examples
Document error conditions
Provide troubleshooting guidance

README Updates

Keep installation instructions current
Update feature lists
Maintain example accuracy
Include breaking changes

Release Process

Semantic Versioning

We follow Semantic Versioning:

MAJOR (1.0.0): Breaking changes
MINOR (0.1.0): New features (backward compatible)
PATCH (0.0.1): Bug fixes (backward compatible)

Release Workflow

Prepare Release
```
npm run prepare-release
```

Create Release PR

git checkout -b release/v1.2.3
# Update version and changelog
git commit -m "chore(release): prepare v1.2.3"

Automated Release (via semantic-release)
```
npm run release
```

Release Checklist

Getting Help

Community Resources

GitHub Discussions - General questions and discussions
GitHub Issues - Bug reports and feature requests
Documentation - Comprehensive guides and API reference

Maintainer Contact

For urgent issues or security concerns:

Create a GitHub issue with appropriate labels
For security issues, use private vulnerability reporting

Response Times

Bug reports: 2-3 business days
Feature requests: 1 week
Pull requests: 3-5 business days
Security issues: 24-48 hours

Recognition

Contributors will be recognized in:

CHANGELOG.md - For significant contributions
README.md - Contributors section
GitHub releases - Release notes acknowledgments

License

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to the Dataproc MCP Server! Your contributions help make this project better for everyone. 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History