# Contributing to MCP Stack Helm Chart

Thank you for your interest in contributing to the MCP Stack Helm Chart! This document provides guidelines and information for contributors.

## Table of Contents

1. [Code of Conduct](#code-of-conduct)
2. [Getting Started](#getting-started)
3. [Development Setup](#development-setup)
4. [Chart Development Guidelines](#chart-development-guidelines)
5. [Testing](#testing)
6. [Submitting Changes](#submitting-changes)
7. [Release Process](#release-process)
8. [Getting Help](#getting-help)

## Code of Conduct

This project follows the [IBM Code of Conduct](https://github.com/IBM/mcp-context-forge/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

## Getting Started

### Prerequisites

- **Kubernetes cluster** (v1.21+) - Minikube, kind, or cloud-managed
- **Helm 3.x** - [Installation guide](https://helm.sh/docs/intro/install/)
- **kubectl** - Configured to access your cluster
- **Git** - For version control

### Repository Structure

```
charts/mcp-stack/
├── Chart.yaml              # Chart metadata
├── values.yaml             # Default configuration values
├── values.schema.json      # JSON schema for values validation
├── templates/              # Kubernetes manifest templates
│   ├── _helpers.tpl        # Template helpers
│   ├── deployment-*.yaml   # Application deployments
│   ├── service-*.yaml      # Kubernetes services
│   ├── configmap-*.yaml    # Configuration maps
│   ├── secret-*.yaml       # Secret templates
│   ├── ingress.yaml        # Ingress configuration
│   ├── hpa-*.yaml          # Horizontal Pod Autoscaler
│   ├── job-migration.yaml  # Database migration job
│   └── NOTES.txt           # Installation notes
├── README.md               # Chart documentation
├── CHANGELOG.md            # Chart changelog
├── CONTRIBUTING.md         # This file
└── .helmignore             # Files to ignore when packaging
```

## Development Setup

### 1. Fork and Clone

```bash
# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack
```

### 2. Set Up Development Environment

```bash
# Add the upstream remote
git remote add upstream https://github.com/IBM/mcp-context-forge.git

# Create a development branch
git checkout -b feature/your-feature-name

# Install chart dependencies (if any)
helm dependency update
```

### 3. Make Your Changes

Edit the chart files as needed. Common changes include:

- **Templates**: Modify Kubernetes manifests in `templates/`
- **Values**: Update default values in `values.yaml`
- **Schema**: Update validation in `values.schema.json`
- **Documentation**: Update `README.md` and template comments

## Chart Development Guidelines

### Helm Chart Best Practices

1. **Follow Helm conventions**:
   - Use lowercase names and hyphens (kebab-case)
   - Prefix template names with chart name
   - Use meaningful labels and annotations

2. **Template Guidelines**:
   - Use `_helpers.tpl` for reusable template snippets
   - Include proper indentation and comments
   - Use `{{- }}` for whitespace control
   - Quote string values in templates

3. **Values Structure**:
   - Group related settings logically
   - Use nested objects for complex configurations
   - Provide sensible defaults
   - Document all values with comments

4. **Resource Management**:
   - Always set resource requests and limits
   - Use appropriate probe configurations
   - Include security contexts where needed
   - Follow least-privilege principle

### Naming Conventions

- **Resources**: Use `{{ include "mcp-stack.fullname" . }}-<component>`
- **Labels**: Use standard Kubernetes labels via `{{ include "mcp-stack.labels" . }}`
- **Selectors**: Match deployment labels consistently
- **Ports**: Use descriptive port names (`http`, `postgres`, `redis`)

### Documentation Standards

- **Inline Comments**: Explain complex template logic
- **values.yaml**: Comment all configuration options
- **README.md**: Keep installation/configuration docs current
- **NOTES.txt**: Provide helpful post-installation guidance

## Testing

### 1. Lint the Chart

```bash
# Run Helm linting
helm lint .

# Check for common issues
helm template . | kubectl apply --dry-run=client -f -
```

### 2. Template Testing

```bash
# Test template rendering
helm template mcp-stack . -f values.yaml

# Test with custom values
helm template mcp-stack . -f test-values.yaml

# Validate against schema
helm template mcp-stack . --validate
```

### 3. Installation Testing

```bash
# Test installation
helm install mcp-stack-test . --namespace test --create-namespace --dry-run

# Test upgrade
helm upgrade mcp-stack-test . --namespace test --dry-run

# Test with different configurations
helm install mcp-stack-test . -f my-values.yaml --namespace test --create-namespace
```

### 4. Integration Testing

```bash
# Deploy to test cluster
helm install mcp-stack-test . --namespace test --create-namespace --wait

# Verify deployment
kubectl get all -n test
helm test mcp-stack-test -n test  # If test hooks are defined

# Clean up
helm uninstall mcp-stack-test -n test
kubectl delete namespace test
```

### 5. Values Schema Testing

```bash
# Test schema validation
helm lint . --strict
helm template . --values invalid-values.yaml  # Should fail with schema errors
```

## Submitting Changes

### 1. Pre-submission Checklist

- [ ] Chart passes `helm lint` without warnings
- [ ] All templates render correctly with default values
- [ ] `values.schema.json` is updated if values structure changed
- [ ] Documentation is updated (README.md, comments)
- [ ] Chart version is bumped appropriately (see [Versioning](#versioning))
- [ ] CHANGELOG.md is updated with your changes
- [ ] Changes are tested on a real Kubernetes cluster

### 2. Commit Guidelines

Follow [Conventional Commits](https://www.conventionalcommits.org/) format:

```
type(scope): description

[optional body]

[optional footer]
```

**Types**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding/updating tests
- `chore`: Maintenance tasks

**Examples**:
```
feat(templates): add horizontal pod autoscaler support
fix(ingress): resolve path routing issues
docs(readme): update installation instructions
```

### 3. Pull Request Process

1. **Create Pull Request**:
   - Use a descriptive title
   - Reference related issues
   - Fill out the PR template completely

2. **PR Requirements**:
   - Pass all CI checks
   - Include tests for new functionality
   - Maintain or improve chart documentation
   - Follow chart versioning guidelines

3. **Review Process**:
   - Address reviewer feedback promptly
   - Keep PR focused and reasonably sized
   - Squash commits if requested

## Release Process

### Versioning

This chart follows [Semantic Versioning](https://semver.org/):

- **MAJOR** (X.0.0): Incompatible API changes
- **MINOR** (0.X.0): Backwards-compatible functionality additions
- **PATCH** (0.0.X): Backwards-compatible bug fixes

### Chart Version Updates

When making changes:

1. **Patch** (0.2.1): Bug fixes, documentation updates
2. **Minor** (0.3.0): New features, new configuration options
3. **Major** (1.0.0): Breaking changes, major refactoring

Update both `version` and `appVersion` in `Chart.yaml`:

```yaml
version: 0.9.0          # Chart version
appVersion: "0.9.0"     # Application version
```

### Release Checklist

1. Update `Chart.yaml` version
2. Update `CHANGELOG.md` with new version
3. Test thoroughly on multiple environments
4. Create release PR
5. Tag release after merge
6. Package and publish chart

## Getting Help

### Resources

- **Documentation**: [ContextForge Docs](https://ibm.github.io/mcp-context-forge/)
- **Helm Documentation**: [https://helm.sh/docs/](https://helm.sh/docs/)
- **Kubernetes Documentation**: [https://kubernetes.io/docs/](https://kubernetes.io/docs/)

### Support Channels

- **Issues**: [GitHub Issues](https://github.com/IBM/mcp-context-forge/issues)
- **Discussions**: [GitHub Discussions](https://github.com/IBM/mcp-context-forge/discussions)
- **Main Project**: [ContextForge](https://github.com/IBM/mcp-context-forge)

### Common Issues

1. **Template Errors**: Check indentation and YAML syntax
2. **Values Validation**: Ensure values match schema
3. **Resource Conflicts**: Use unique names with fullname template
4. **Permission Issues**: Check RBAC settings and service accounts

## Thank You

Your contributions help make the MCP ContextForge Stack easier to deploy and manage for everyone. We appreciate your time and effort in improving this project!

---

*This document is based on the [ContextForge](https://github.com/IBM/mcp-context-forge) project and follows established open-source contribution practices.*
