Contributing to SegnoMMS

Thank you for your interest in contributing to SegnoMMS! This document provides guidelines for contributing to the project.

Development Setup

Clone the repository:

git clone https://github.com/systmms/segnomms.git
cd segnomms

Set up development environment:
```
make setup
```
Install git hooks (Lefthook):
```
lefthook install
```
Lefthook manages git hooks for code quality checks including:
- actionlint: GitHub Actions workflow validation
- black: Python code formatting
- isort: Import sorting
- flake8: Python linting
- mypy: Type checking
- bandit: Security analysis
Hooks run automatically on commit. To run manually:
```
lefthook run pre-commit
```

Development Workflow

Code Quality Standards

MyPy: All code must pass strict type checking with zero errors
Black: All Python code must be formatted with Black
isort: All imports must be properly sorted and organized
flake8: All code must pass linting checks
Tests: All existing tests must pass before committing

Discovering Available Commands

Use make help to discover all available Makefile targets:

make help

This displays all commands organized by category (setup, testing, documentation, etc.)

Running Tests

# Run all tests
make test

# Run specific test categories
make test-unit
make test-integration
make test-visual
make test-structural
make test-performance

# Run quick tests during development
make test-quick

Test Script Discoverability Policy:

All permanent test scripts must have corresponding Makefile targets to ensure discoverability. When creating new test scripts:

Permanent scripts (regression tests, compatibility tests, benchmarks): Add a Makefile target
Temporary scripts (one-off debugging): No Makefile target needed
Use make help to verify your script is discoverable

Documentation

Update documentation when adding new features
All public APIs must have comprehensive docstrings
Run make docs to build documentation locally
Documentation uses Sphinx with RST format

Git Commit Standards

NEVER use ``–no-verify`` flag with git commits.

Lefthook git hooks exist to maintain code quality and consistency
All formatting, linting, and type checking issues must be resolved before committing
If git hooks fail, fix the underlying issues rather than bypassing them
Commits must follow Conventional Commits format

Submitting Changes

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes:
- Write code following the established patterns
- Add tests for new functionality
- Update documentation as needed
Test your changes:
```
make test
make docs
```

Commit your changes:

git add .
git commit -m "feat: add your feature description"

Push and create a pull request:

git push origin feature/your-feature-name

Code Review Process

All changes must be reviewed via pull request
Ensure all CI checks pass
Address any review feedback
Maintain clean commit history

Spec-Kit Workflow (Feature Development)

SegnoMMS uses GitHub Spec-Kit for spec-driven feature development with AI agents.

Available Slash Commands:

# Create/update project constitution
/speckit.constitution

# Create feature specification from natural language
/speckit.specify

# Clarify underspecified areas in spec
/speckit.clarify

# Generate technical implementation plan
/speckit.plan

# Generate actionable task list
/speckit.tasks

# Execute implementation plan
/speckit.implement

# Analyze cross-artifact consistency
/speckit.analyze

Workflow Phases:

Constitution: Define project principles (already established)
Specification: Describe WHAT users need and WHY
Planning: Generate HOW to implement (technical plan)
Tasks: Break down into actionable work items
Implementation: Execute tasks with validation

Validation:

make spec-check      # Validate spec-kit installation
make spec-validate   # Check specification files
make spec-help       # Show complete workflow guide

All spec-driven features must pass existing quality gates (MyPy, tests, pre-commit hooks).

Getting Help

Check existing issues and discussions
Create an issue for bug reports or feature requests
Join our community discussions for general questions

License

By contributing to SegnoMMS, you agree that your contributions will be licensed under the project’s license.