Workflow Conventions

Git workflow and contribution guidelines for EAC monorepo contributors.

Branching Strategy

The EAC repository uses trunk-based development:

main - The trunk; always deployable
Feature branches - Short-lived branches for changes
No long-lived branches - Merge within days, not weeks

Branch Naming

<type>/<short-description>

Examples:
  feat/add-scan-command
  fix/config-loading-error
  docs/update-getting-started
  refactor/simplify-module-loader

Types:

Type	Purpose
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`refactor`	Code restructuring
`test`	Test additions/fixes
`chore`	Maintenance tasks

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Examples:

feat(commands): add scan-zap command for DAST scanning

fix(core): resolve config loading race condition

docs(reference): update command cheat sheet

test(eac-commands): add integration tests for build command

Scopes (optional but helpful):

commands - EAC commands
core - eac-core module
cli - CLIE CLI
docs - Documentation
ci - CI/CD workflows

Pull Request Workflow

1. Create Branch

git checkout main
git pull origin main
git checkout -b feat/my-feature

2. Make Changes

Keep commits atomic and focused
Run tests locally: eac test <module>
Validate contracts: eac validate

3. Push and Create PR

git push -u origin feat/my-feature

Then create PR via GitHub or:

eac create pr

4. PR Requirements

Before merge, PRs must:

[ ] Pass all CI checks
[ ] Have passing tests
[ ] Pass contract validation
[ ] Have descriptive title and description
[ ] Be reviewed (if required)

5. Merge

Use squash merge for feature branches
Delete branch after merge

Code Review Guidelines

For Authors:

Keep PRs small and focused
Provide context in description
Respond to feedback promptly

For Reviewers:

Review within 24 hours
Be constructive and specific
Approve when ready, request changes when needed

CI/CD Pipeline

Every push triggers:

Contract Validation - Schema and reference checks
Build - Compile all affected modules
Test - Run test suites
Lint - Code style checks

View CI status:

eac pipeline status

Release Process

Releases are triggered by changelog updates:

Update module's CHANGELOG.md
Add version entry with changes
Merge to main
CI creates tag and release

Check release readiness:

eac release check-ci <module>

Working with Modules

Find Affected Modules

# See which modules changed
eac get changed-modules

# Build only changed modules
eac build --changed

Module Dependencies

# View dependency graph
eac show dependencies

# Build with dependencies
eac build <module> --deps

Best Practices

Small, focused changes - Easier to review and merge
Test before pushing - Catch issues early
Update docs with code - Keep documentation current
Validate contracts - Run eac validate before committing
Use conventional commits - Enables automated changelog generation

Troubleshooting

CI Failing

# Run same checks locally
eac validate
eac test <module>
eac lint <module>

Merge Conflicts

# Rebase on main
git fetch origin
git rebase origin/main

# Or merge main into branch
git merge origin/main

Stale Branch

If branch is old:

git checkout main
git pull
git checkout feat/my-feature
git rebase main