Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
206 lines (150 loc) · 4.14 KB

CONTRIBUTING.md

File metadata and controls

206 lines (150 loc) · 4.14 KB

Contributing to Groundkeeper

Thank you for your interest in contributing to Groundkeeper! This document provides guidelines and instructions for contributing.

Development Setup

  1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/groundkeeper.git
cd groundkeeper
  1. Install dependencies
npm install
  1. Build the project
npm run build
  1. Run tests
npm test

Project Structure

groundkeeper/
├── src/
│   ├── __tests__/          # Test files
│   ├── phases/             # Phase implementations
│   │   ├── Phase.ts        # Base phase class
│   │   ├── ScanPhase.ts    # Scan phase
│   │   ├── AnalyzePhase.ts # Analyze phase
│   │   ├── PlanPhase.ts    # Plan phase
│   │   ├── ProposePhase.ts # Propose phase
│   │   └── ActPhase.ts     # Act phase
│   ├── groundkeeper.ts        # Main Groundkeeper class
│   ├── cli.ts              # CLI entry point
│   ├── config.ts           # Configuration loader
│   ├── types.ts            # TypeScript types
│   └── index.ts            # Public API exports
├── dist/                   # Compiled JavaScript (committed for GitHub Actions)
├── action.yml              # GitHub Action manifest
├── package.json
├── tsconfig.json
└── README.md

Development Workflow

  1. Create a feature branch
git checkout -b feature/your-feature-name
  1. Make your changes
  • Write code following the existing style
  • Add tests for new functionality
  • Update documentation as needed
  1. Run tests
npm test
  1. Build the project
npm run build
  1. Test locally
node dist/cli.js run
  1. Commit your changes
git add .
git commit -m "Description of your changes"
  1. Push and create a pull request
git push origin feature/your-feature-name

Code Style

  • Use TypeScript for all code
  • Follow existing naming conventions
  • Add JSDoc comments for public APIs
  • Keep functions focused and testable
  • Use meaningful variable names

Testing

  • Write tests for all new functionality
  • Place tests in src/__tests__/
  • Use descriptive test names
  • Aim for high code coverage

Example test:

describe('MyFeature', () => {
  it('should do something specific', () => {
    // Arrange
    const input = 'test';
    
    // Act
    const result = myFunction(input);
    
    // Assert
    expect(result).toBe('expected');
  });
});

Adding New Phases

To add a new phase:

  1. Create a new file in src/phases/ (e.g., MyPhase.ts)
  2. Extend the Phase base class
  3. Implement the run method
  4. Export from src/phases/index.ts
  5. Add to the phase list in src/groundkeeper.ts
  6. Add tests in src/__tests__/

Example:

import { Phase } from './Phase';
import { GroundkeeperContext } from '../types';

export class MyPhase extends Phase {
  name = 'my-phase';

  protected async run(context: GroundkeeperContext): Promise<any> {
    // Your phase logic here
    return { result: 'data' };
  }
}

Adding New Task Types

To add a new task type for the analyze phase:

  1. Add a new case in AnalyzePhase.analyzeTask()
  2. Create a private method for the analysis
  3. Return findings as Finding[]
  4. Document the task type in README.md

Building for Release

Before creating a release:

  1. Update version in package.json
  2. Update CHANGELOG.md (if exists)
  3. Run npm run build
  4. Commit the updated dist/ directory
  5. Create a git tag
npm version patch # or minor, or major
npm run build
git add dist/
git commit -m "Build for release"
git tag -a v1.0.1 -m "Version 1.0.1"
git push origin main --tags

Reporting Issues

When reporting issues, please include:

  • Groundkeeper version
  • Node.js version
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages or logs

Questions?

Feel free to open an issue for any questions about contributing!

License

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