CONTRIBUTING.md

Contributing to FinEE

Thank you for your interest in contributing! Here's how to get started.

🚨 Golden Rules

1. NEVER push directly to main - All changes go through PRs
2. All features branch from develop - Not from main
3. Tests MUST pass before merging - No exceptions
4. Update CHANGELOG.md - Every PR should update it

🌿 Branching Strategy (Git Flow)

main          ──●────────────────●────────────●──→  (releases only)
                │                │            │
              v1.0.3          v1.0.4        v1.1.0
                │                │            │
develop       ──●────●────●──────●───●────●───●──→  (integration)
                     │    │          │    │
feature/a     ───────●────┘          │    │
feature/b     ───────────────────────●────┘

Branch Types

Branch	Source	Merges To	Naming
main	-	-	Protected, releases only
develop	main	main	Integration branch
feature/*	develop	develop	feature/add-kotak-support
fix/*	develop	develop	fix/unicode-amount-parsing
hotfix/*	main	main + develop	hotfix/critical-regex-bug

🔄 Development Workflow

1. Start a New Feature

# Always start from develop
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/my-awesome-feature

# Make changes...
# Write tests...
# Update CHANGELOG.md under [Unreleased]

# Commit with conventional messages
git commit -m "feat: add support for Paytm VPA patterns"

# Push and create PR
git push -u origin feature/my-awesome-feature
# Create PR: feature/my-awesome-feature → develop

2. Fix a Bug

git checkout develop
git pull origin develop
git checkout -b fix/issue-123-unicode-error

# Fix the bug...
# Add test to prevent regression...

git commit -m "fix: handle ₹ symbol in amount parsing"
git push -u origin fix/issue-123-unicode-error
# Create PR: fix/issue-123-unicode-error → develop

3. Create a Release

Use the release script:

# Preview what will happen
python scripts/release.py 1.0.4 --dry-run

# Execute release
python scripts/release.py 1.0.4

The script will:

1. ✅ Verify you're on develop
2. ✅ Run all tests
3. ✅ Run benchmark suite
4. ✅ Update version in pyproject.toml
5. ✅ Update CHANGELOG.md
6. ✅ Merge to main
7. ✅ Create git tag v1.0.4
8. ✅ Build and upload to PyPI
9. ✅ Return to develop

🧪 Pre-Merge Checklist

Before your PR can be merged:

• All tests pass: pytest tests/ -v
• Benchmark runs: python benchmark.py --all
• CHANGELOG.md updated under [Unreleased]
• Code formatted: black src/ tests/
• Linting passes: ruff check src/ tests/
• New features have tests
• Documentation updated if needed

📋 Commit Message Format

Use Conventional Commits:

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

[optional body]

[optional footer]

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation only
test	Adding tests
refactor	Code refactoring
perf	Performance improvement
chore	Maintenance tasks

Examples

feat(regex): add Lakhs notation support
fix(parser): handle missing spaces in SMS
docs: update README with torture tests
test: add edge cases for Unicode symbols
chore: move notebooks to experiments/

📝 Changelog Guidelines

Update CHANGELOG.md in every PR under [Unreleased]:

## [Unreleased]
### Added
- New feature you added

### Changed
- Behavior you modified

### Fixed
- Bug you fixed

Categories:

• Added - New features
• Changed - Changes to existing features
• Deprecated - Features to be removed
• Removed - Removed features
• Fixed - Bug fixes
• Security - Security fixes

🛡️ Protected Branches

Branch	Direct Push	Force Push	PR Required
main	❌	❌	✅ (from develop only)
develop	❌	❌	✅ (from feature/fix)

🙏 Thank You!

Every contribution makes FinEE better for the Indian fintech community!