docs: update contribution guidelines and branch strategy

.github/BRANCH_STRATEGY.md

@@ -0,0 +1,150 @@
+# Branch Strategy Guide
+
+This document provides detailed examples and workflows for contributing to Captioneer using our branching strategy.
+
+## Branch Types
+
+### Main Branches
+
+#### main
+
+- Production-ready code
+- Tagged releases
+- Direct commits not allowed
+
+```bash
+git checkout main
+git pull origin main
+```
+
+### develop
+
+- Integration branch
+- Base for feature development
+
+```bash
+git checkout develop
+git pull origin develop
+```
+
+## Feature Development
+
+### Starting a New Feature
+
+```bash
+git checkout develop
+git checkout -b feature/language-detection
+```
+
+### Working on the Feature
+
+```bash
+git add .
+git commit -m "feat: implement language detection"
+git push origin feature/language-detection
+```
+
+### Completing the Feature
+
+```bash
+# Update with latest develop changes
+git checkout develop
+git pull origin develop
+git checkout feature/language-detection
+git rebase develop
+
+# Push feature
+git push origin feature/language-detection
+```
+
+## Bug Fixes
+
+### Creating a Bug Fix
+
+```bash
+git checkout develop
+git checkout -b fix/parsing-error
+```
+
+### Implementing the Fix
+
+```bash
+git add .
+git commit -m "fix: resolve caption parsing error"
+git push origin fix/parsing-error
+```
+
+## Documentation
+
+### Documentation Updates
+
+```bash
+git checkout develop
+git checkout -b docs/api-examples
+```
+
+## Releases
+
+### Preparing a Release
+
+```bash
+git checkout develop
+git checkout -b release/1.1.0
+```
+
+### Finalizing a Release
+
+```bash
+# Merge to main
+git checkout main
+git merge release/1.1.0
+git tag -a v1.1.0 -m "Release 1.1.0"
+git push origin main --tags
+
+# Back merge to develop
+git checkout develop
+git merge release/1.1.0
+git push origin develop
+```
+
+## Hotfixes
+### Creating a Hotfix
+
+```bash
+git checkout main
+git checkout -b hotfix/1.0.1
+```
+
+### Applying a Hotfix
+
+```bash
+# Merge to main
+git checkout main
+git merge hotfix/1.0.1
+git tag -a v1.0.1 -m "Hotfix 1.0.1"
+git push origin main --tags
+
+# Back merge to develop
+git checkout develop
+git merge hotfix/1.0.1
+git push origin develop
+```
+
+## Pull Request Guidelines
+1. Create PR from your feature branch to develop 
+2. Ensure CI checks pass 
+3. Request review from maintainers 
+4. Address review feedback 
+5. Squash and merge when approved
+
+## Best Practices
+1. Keep branches focused and short-lived 
+2. Regularly sync with develop 
+3. Write clear commit messages 
+4. Delete branches after merging 
+5. Never force push to main or develop
+
+## Branch Protection Rules
+- main: Requires PR and approvals 
+- develop: Requires PR and approvals 
+- All branches: Must pass CI checks

CONTRIBUTING.md

@@ -4,7 +4,7 @@ We love your input! We want to make contributing to Captioneer as easy and trans
 
 ## Development Process
 
-1. Fork the repo and create your branch from `main`.
+1. Fork the repo and create your branch from `develop`
 2. Install dependencies with `pnpm install`
 3. Make your changes
 4. Add tests for any new functionality
@@ -13,18 +13,49 @@ We love your input! We want to make contributing to Captioneer as easy and trans
 7. Run linting with `pnpm check`
 8. Submit your pull request
 
+## Branching Strategy
+
+Our repository follows this branching model:
+
+### Main Branches
+
+- `main` - Production-ready code
+- `develop` - Integration branch for features
+
+### Development Branches
+
+- `feature/*` - New features (e.g., feature/add-language-detection)
+- `fix/*` - Bug fixes (e.g., fix/parsing-error)
+- `docs/*` - Documentation updates (e.g., docs/api-examples)
+
+### Release Branches
+
+- `release/*` - Version preparation (e.g., release/1.1.0)
+- `hotfix/*` - Urgent production fixes (e.g., hotfix/1.0.1)
+
+### Workflow
+
+1. Create feature branches from `develop`
+2. Submit pull requests to merge into `develop`
+3. Create release branches for version preparation
+4. Merge releases into both `main` and `develop`
+5. Tag releases on `main` for semantic versioning
+
 ## Pull Request Process
 
 1. Update the README.md with details of changes if needed
 2. Update the CHANGELOG.md with your changes
-3. The PR will be merged once you have the sign-off of a maintainer
+3. Follow the conventional commits specification for commit messages
+4. Include relevant test cases
+5. The PR will be merged once you have the sign-off of a maintainer
 
 ## Code Style
 
 - Use TypeScript
-- Follow the existing code style
+- Follow the existing code style enforced by Biome
 - Write meaningful commit messages following conventional commits
 - Add tests for new features
+- Keep code coverage high
 
 ## Running Tests
 
@@ -39,5 +70,37 @@ pnpm test:watch
 pnpm test:coverage
 ```
 
+## Commit Messages
+
+Follow the conventional commits' specification:
+
+```textmate
+# Feature
+feat: add new language detection
+
+# Bug fix
+fix: resolve parsing error
+
+# Documentation
+docs: update API examples
+```
+
+## Development Scripts
+
+```bash
+# Build the project
+pnpm build
+
+# Development mode
+pnpm dev
+
+# Type checking
+pnpm typecheck
+
+# Linting
+pnpm check
+```
+
 ## License
-By contributing, you agree that your contributions will be licensed under the MIT License.
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

README.md

@@ -135,13 +135,22 @@ pnpm lint
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! We follow a structured branching strategy and conventional commits.
 
+### Quick Start
 1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+2. Create your feature branch from `develop` (`git checkout -b feature/amazing-feature`)
+3. Write meaningful commit messages following conventional commits (`feat: add amazing feature`)
+4. Push to your branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request to `develop`
+
+### Detailed Guidelines
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines
+- Check [.github/BRANCH_STRATEGY.md](.github/BRANCH_STRATEGY.md) for branch workflows
+- Follow our [Code of Conduct](CODE_OF_CONDUCT.md)
+
+Your contributions help make Captioneer better for everyone!
+
 
 ## License