@cirrusinvicta/ai-commit-toolkit/CONTRIBUTING.md

AI-powered conventional commit generation with centralized configuration, OpenAI integration, and automated deployment workflows

# Contributing to AI Commit Toolkit

Thank you for your interest in contributing to the AI Commit Toolkit! This document provides guidelines and instructions for contributors.

## 🚀 Getting Started

### Prerequisites

- **Node.js**: Version 16.0.0 or higher
- **npm**: Version 8.0.0 or higher
- **Git**: For version control
- **OpenAI API Key**: For testing AI functionality (optional for non-AI tests)

### Initial Setup

1. **Clone the repository**:

   ```bash
   git clone https://github.com/CirrusInvicta/ai-commit-toolkit.git
   cd ai-commit-toolkit
   ```

2. **Install dependencies**:

   ```bash
   npm install
   ```

3. **Setup development environment**:

   ```bash
   npm run prepare  # Sets up Husky hooks for commit validation
   ```

4. **Verify installation**:
   ```bash
   npm test  # Runs all tests to ensure everything works
   ```

## 🛠️ Development Workflow

### Making Changes

1. **Create a feature branch**:

   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   ```

2. **Make your changes** following the coding standards below

3. **Run tests frequently**:

   ```bash
   npm run test:unit     # Fast unit tests
   npm run test:config   # Configuration validation
   npm test              # Full integration tests
   ```

4. **Commit your changes** using conventional commits:
   ```bash
   git add .
   git commit -m "feat: add new feature description"
   ```

### Coding Standards

- **JavaScript**: Follow existing code style and patterns
- **File naming**: Use kebab-case for files and directories
- **Functions**: Use clear, descriptive names
- **Comments**: Add JSDoc comments for public methods
- **Error handling**: Always handle errors appropriately
- **Dependencies**: Prefer latest stable versions

### Commit Message Format

This project enforces [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Types:**

- `feat:` - New features (minor version bump)
- `fix:` - Bug fixes (patch version bump)
- `docs:` - Documentation changes
- `style:` - Code style changes (no logic changes)
- `refactor:` - Code refactoring
- `test:` - Adding or updating tests
- `chore:` - Maintenance tasks
- `ci:` - CI/CD changes
- `perf:` - Performance improvements
- `build:` - Build system changes

**Breaking Changes:**

- Add `!` after type: `feat!: change API behavior`
- Or include `BREAKING CHANGE:` in footer

**Examples:**

```bash
git commit -m "feat: add support for custom AI prompts"
git commit -m "fix: resolve package-lock.json exclusion issue"
git commit -m "docs: update installation instructions"
git commit -m "feat!: change default configuration format"
```

## 🧪 Testing

### Test Categories

The project has comprehensive testing with multiple categories:

1. **Unit Tests** (`test/unit/`):

   - Test individual functions and classes
   - Mock external dependencies
   - Fast execution (< 2 seconds)

2. **Integration Tests** (`test/integration/`):

   - Test complete workflows
   - Test real file operations
   - Validate end-to-end functionality

3. **Configuration Tests** (`test/config-test.sh`):
   - Validate configuration file structure
   - Test variable loading and substitution
   - Verify exclusion patterns

### Running Tests

```bash
# Run all tests (recommended before commits)
npm test

# Run specific test types
npm run test:unit        # Unit tests only (73 tests)
npm run test:integration # Integration tests only
npm run test:config      # Configuration validation
npm run test:all         # Unit + Integration tests

# Run tests with coverage
npm run test:unit -- --coverage

# Run specific test files
npx jest test/unit/setup.test.js
npx jest test/unit/setup.test.js --watch  # Watch mode
```

### Writing Tests

When adding new features, always include tests:

1. **Unit tests** for new functions/classes
2. **Integration tests** for new workflows
3. **Configuration tests** for new config options

**Test file naming:**

- Unit tests: `test/unit/YourFeature.test.js`
- Integration tests: `test/integration/your-feature.sh`

**Unit test example:**

```javascript
describe("YourFeature", () => {
  describe("methodName", () => {
    it("should do something specific", () => {
      // Arrange
      const input = "test data";

      // Act
      const result = yourMethod(input);

      // Assert
      expect(result).toBe("expected output");
    });
  });
});
```

### Test Requirements

- All new code must have test coverage
- Unit tests should not require external dependencies
- Integration tests should clean up after themselves
- Tests should be deterministic and repeatable

## 🏗️ Project Structure

```
ai-commit-toolkit/
├── bin/                    # Executable commands
│   ├── ai-commit          # Main AI commit command
│   ├── ai-commit-helper   # Interactive helper
│   ├── ai-commit-setup    # Setup command
│   └── ai-commit-test     # Testing command
├── lib/                    # Core library code
│   └── setup.js           # Main setup logic
├── templates/              # Template files
│   ├── config/            # Configuration templates
│   ├── hooks/             # Git hook templates
│   └── scripts/           # Script templates
├── test/                   # Test files
│   ├── unit/              # Unit tests (Jest)
│   ├── integration/       # Integration tests (Bash)
│   ├── config-test.sh     # Configuration validation
│   └── simple-integration.sh # Basic integration tests
├── docs/                   # Documentation
├── index.js               # Main entry point
├── package.json           # Package configuration
└── README.md              # User documentation
```

### Key Files

- **`lib/setup.js`**: Core setup logic, dependency management
- **`templates/config/ai-prompts.conf`**: AI configuration template
- **`templates/hooks/`**: Git hook templates
- **`bin/`**: Command-line interfaces
- **`test/unit/`**: Comprehensive unit test suite

## 📦 Release Process

This project uses automated semantic versioning with semantic-release.

### Version Bumping

Versions are automatically determined by commit messages:

- **Patch** (`1.0.0` → `1.0.1`): `fix:` commits
- **Minor** (`1.0.0` → `1.1.0`): `feat:` commits
- **Major** (`1.0.0` → `2.0.0`): `feat!:` or `BREAKING CHANGE:` commits

### Release Workflow

1. **Prepare your changes**:

   ```bash
   # Ensure all tests pass
   npm test

   # Ensure dependencies are up to date
   npm audit
   ```

2. **Create a release branch** (optional for major releases):

   ```bash
   git checkout -b release/v2.0.0
   ```

3. **Merge to main**:

   ```bash
   # Create merge request to main branch
   # Semantic-release automatically handles versioning and publishing
   ```

4. **Monitor the release**:
   - Check GitHub Actions CI/CD pipeline
   - Verify npm package publication
   - Review generated CHANGELOG.md

### Pre-release Testing

Before major releases, test the package locally:

```bash
# Build the package
npm pack

# Test in a separate project
cd /tmp && mkdir test-project && cd test-project
git init
npm init -y
npm install /path/to/ai-commit-toolkit/cirrusinvicta-ai-commit-toolkit-X.X.X.tgz
npx ai-commit-toolkit setup --yes
```

### Manual Release (Emergency)

If automated releases fail:

```bash
# Bump version manually
npm version patch|minor|major

# Publish to npm
npm publish

# Create git tag
git push origin main --tags
```

## 🔧 Configuration Management

### Adding New Configuration Options

1. **Update template** (`templates/config/ai-prompts.conf`):

   ```bash
   # Add new configuration variable
   NEW_OPTION="default_value"
   ```

2. **Update setup logic** (`lib/setup.js`):

   ```javascript
   // Handle the new configuration in setup process
   ```

3. **Add tests** (`test/config-test.sh`):

   ```bash
   # Validate new configuration option
   ```

4. **Update documentation** (`README.md`, `docs/`):
   - Explain the new option
   - Provide usage examples

### Configuration Best Practices

- Use descriptive variable names
- Provide sensible defaults
- Validate configuration values
- Document all options thoroughly
- Maintain backward compatibility

## 🐛 Bug Reports

### Before Submitting

1. **Check existing issues** in GitHub Issues
2. **Update to latest version**: `npm update @cirrusinvicta/ai-commit-toolkit`
3. **Run diagnostic tests**: `npx ai-commit-test`
4. **Check logs** for error messages

### Bug Report Template

```markdown
**Bug Description:**
A clear description of the bug.

**Steps to Reproduce:**

1. Step one
2. Step two
3. Step three

**Expected Behavior:**
What should happen.

**Actual Behavior:**
What actually happens.

**Environment:**

- OS: [e.g., macOS 12.0, Ubuntu 20.04]
- Node.js version: [e.g., 18.0.0]
- npm version: [e.g., 8.0.0]
- Toolkit version: [e.g., 1.2.3]

**Additional Context:**

- Error logs
- Configuration files
- Screenshots (if applicable)
```

## 💡 Feature Requests

### Before Submitting

1. **Search existing issues** for similar requests
2. **Consider the scope** - does it fit the project goals?
3. **Think about implementation** - is it technically feasible?

### Feature Request Template

```markdown
**Feature Description:**
Clear description of the proposed feature.

**Use Case:**
Why is this feature needed? What problem does it solve?

**Proposed Solution:**
How do you envision this working?

**Alternatives Considered:**
What other approaches have you considered?

**Additional Context:**
Any other relevant information.
```

## 🤝 Code Review Process

### For Contributors

1. **Self-review** your code before submitting
2. **Write clear commit messages** following conventional commits
3. **Include tests** for new functionality
4. **Update documentation** as needed
5. **Keep PRs focused** - one feature/fix per PR

### For Reviewers

1. **Test the changes** locally
2. **Check code quality** and consistency
3. **Verify documentation** is updated
4. **Ensure tests pass** and coverage is maintained
5. **Provide constructive feedback**

## 📞 Getting Help

- **Issues**: GitHub Issues for bugs and feature requests
- **Documentation**: Check README.md and docs/ folder
- **Email**: jmatz@cirrusinvicta.com for urgent matters

## 📄 License

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

---

Thank you for contributing to the AI Commit Toolkit! 🎉