# Contributing Guide
This guide will help you understand our development practices and contribution workflow.
## 📋 Quick Reference
| DDD layer placement (architecture) | [ddd-layer-placement.md](./ddd-layer-placement.md) |
| DDD practices (domain patterns) | [ddd-practices.md](./ddd-practices.md) |
| PR review guide for reviewers | [pr-review-guide.md](./pr-review-guide.md) |
| Creating roadmap issues | [roadmap-issues.md](./roadmap-issues.md) |
| Branching conventions | [branching.md](./branching.md) |
| Commit process and pre-commit checks | [commit-process.md](./commit-process.md) |
| Code quality and linting | [linting.md](./linting.md) |
| Module organization and imports | [module-organization.md](./module-organization.md) |
| Error handling principles | [error-handling.md](./error-handling.md) |
| Output handling with UserOutput | [output-handling.md](./output-handling.md) |
| Secret handling (sensitive data) | [secret-handling.md](./secret-handling.md) |
| Working with Tera templates | [templates/](./templates/) |
| Environment variables naming | [environment-variables-naming.md](./environment-variables-naming.md) |
| Debugging techniques | [debugging.md](./debugging.md) |
| Spell checking and dictionaries | [spelling.md](./spelling.md) |
| Known issues and expected behaviors | [known-issues.md](./known-issues.md) |
| Logging best practices | [logging-guide.md](./logging-guide.md) |
| GitHub Markdown pitfalls | [github-markdown-pitfalls.md](./github-markdown-pitfalls.md) |
| GitHub Copilot agent configuration | [copilot-agent/](./copilot-agent/) |
| Testing conventions and practices | [testing/](./testing/) |
## 🚀 Getting Started
1. **Fork and clone** the repository
2. **Install dependencies** using the automated installer:
```bash
cargo run --bin dependency-installer install
```
See [Dependency Installer](../../packages/dependency-installer/README.md) for details.
3. **Read the branching** guidelines in [branching.md](./branching.md)
4. **Install and run linters** as described in [linting.md](./linting.md)
5. **Follow the commit process** outlined in [commit-process.md](./commit-process.md)
## 🔧 Development Workflow Summary
```bash
# 1. Create a feature branch (use issue number)
git checkout -b 42-add-your-feature-name
# 2. Make your changes
# ... edit files ...
# 3. Run pre-commit verification script
./scripts/pre-commit.sh
# 4. Commit with conventional format (include issue number)
git add .
git commit -m "feat: [#42] add new testing feature"
# 5. Push and create PR
git push origin 42-add-your-feature-name
```
## Dependency Update Automation
For dependency-only updates, you can automate the repetitive git and PR workflow with:
```bash
./scripts/update-dependencies.sh \
--branch 445-update-dependencies \
--push-remote josecelano \
--create-pr
```
Notes:
- The script signs commits by default with `git commit -S`.
- The push remote and branch name are explicit so the workflow works with different forks.
- Reuse `--delete-existing-branch` only when you intentionally want to replace an older update branch.
- Use `--help` to see all options.
## 📖 Additional Resources
- [Main Documentation](../documentation.md) - Project documentation organization
- [E2E Testing Guide](../e2e-testing.md) - End-to-end testing setup and usage
- [Linting Guide](../linting.md) - Detailed linting setup and usage
- [Tech Stack](../tech-stack/) - Technology-specific documentation
- [Architecture Decisions](../decisions/) - Decision records and rationale
## 🤝 Getting Help
- **Issues**: Check existing [GitHub issues](https://github.com/torrust/torrust-tracker-deployer/issues)
- **Discussions**: Start a [GitHub discussion](https://github.com/torrust/torrust-tracker-deployer/discussions)
- **Documentation**: Review the [docs folder](../) for detailed information
Thank you for contributing! 🎉