Skip to content

Commit 2d1123b

Browse files
josecelanojosecelano
committed
docs: add comprehensive contribution guidelines
Add structured contribution documentation including: - Branching conventions with issue-number-based naming - Commit process with conventional commits and issue tracking - Linting tools configuration and usage guidelines - Development workflow and pre-commit checks The new docs/contributing/ folder provides clear guidance for contributors on code quality, Git workflow, and project conventions.
1 parent f4752b9 commit 2d1123b

File tree

7 files changed

+644
-0
lines changed

7 files changed

+644
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -276,6 +276,7 @@ The repository includes comprehensive GitHub Actions workflows for CI testing:
276276

277277
## 📚 Documentation
278278

279+
- **[🤝 Contributing Guide](docs/contributing/README.md)** - Git workflow, commit process, and linting conventions
279280
- **[📖 Documentation Organization Guide](docs/documentation.md)** - How documentation is organized and where to contribute
280281
- **[📖 OpenTofu Setup Guide](docs/tech-stack/opentofu.md)** - Installation, common commands, and best practices
281282
- **[📖 Ansible Setup Guide](docs/tech-stack/ansible.md)** - Installation, configuration, and project usage

‎docs/contributing/README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Contributing Guide
2+
3+
This guide will help you understand our development practices and contribution workflow.
4+
5+
## 📋 Quick Reference
6+
7+
| Topic | File |
8+
| ------------------------------------ | ---------------------------------------- |
9+
| Branching conventions | [branching.md](./branching.md) |
10+
| Commit process and pre-commit checks | [commit-process.md](./commit-process.md) |
11+
| Code quality and linting | [linting.md](./linting.md) |
12+
13+
## 🚀 Getting Started
14+
15+
1. **Fork and clone** the repository
16+
2. **Set up your development environment** following the main [README](../../README.md)
17+
3. **Read the branching** guidelines in [branching.md](./branching.md)
18+
4. **Install and run linters** as described in [linting.md](./linting.md)
19+
5. **Follow the commit process** outlined in [commit-process.md](./commit-process.md)
20+
21+
## 🔧 Development Workflow Summary
22+
23+
```bash
24+
# 1. Create a feature branch (use issue number)
25+
git checkout -b 42-add-your-feature-name
26+
27+
# 2. Make your changes
28+
# ... edit files ...
29+
30+
# 3. Run linters before committing
31+
./scripts/linting/lint.sh all
32+
33+
# 4. Run tests
34+
cargo test
35+
cargo run --bin e2e-tests wait-cloud-init
36+
37+
# 5. Commit with conventional format (include issue number)
38+
git add .
39+
git commit -m "feat: [#42] add new testing feature"
40+
41+
# 6. Push and create PR
42+
git push origin 42-add-your-feature-name
43+
```
44+
45+
## 📖 Additional Resources
46+
47+
- [Main Documentation](../documentation.md) - Project documentation organization
48+
- [Linting Guide](../linting.md) - Detailed linting setup and usage
49+
- [Tech Stack](../tech-stack/) - Technology-specific documentation
50+
- [Architecture Decisions](../decisions/) - Decision records and rationale
51+
52+
## 🤝 Getting Help
53+
54+
- **Issues**: Check existing [GitHub issues](https://github.com/josecelano/torrust-testing-infra-poc/issues)
55+
- **Discussions**: Start a [GitHub discussion](https://github.com/josecelano/torrust-testing-infra-poc/discussions)
56+
- **Documentation**: Review the [docs folder](../) for detailed information
57+
58+
Thank you for contributing! 🎉

‎docs/contributing/branching.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Branching Conventions
2+
3+
This document outlines the branching conventions for the Torrust Testing Infrastructure project.
4+
5+
## 🌿 Branch Naming
6+
7+
- **Format**: `{issue-number}-{short-description-following-github-conventions}`
8+
- **GitHub conventions**: Use lowercase, separate words with hyphens, descriptive but concise
9+
- **Examples**: `42-add-mysql-support`, `15-fix-ssl-renewal`, `24-improve-ux-add-automatic-waiting-to-infra-apply-and-app-deploy-commands`
10+
- Always start with the GitHub issue number
11+
- Follow GitHub's recommended branch naming: lowercase, hyphens for word separation, descriptive of the change
12+
13+
### Examples
14+
15+
```bash
16+
# Good branch names
17+
git checkout -b 42-add-mysql-support
18+
git checkout -b 15-fix-ssl-renewal
19+
git checkout -b 89-update-contributing-guide
20+
git checkout -b 156-refactor-ansible-inventory-structure
21+
git checkout -b 203-add-e2e-multipass-tests
22+
23+
# Avoid
24+
git checkout -b my-feature # No issue number
25+
git checkout -b FEATURE-123 # All caps
26+
git checkout -b fix_bug # Underscores instead of hyphens
27+
git checkout -b 42_add_support # Underscores instead of hyphens
28+
git checkout -b 42-Add-Support # Mixed case
29+
```
30+
31+
## 📋 Branch Lifecycle
32+
33+
1. **Create**: `git checkout -b {issue-number}-{description}`
34+
2. **Develop**: Make commits following [commit conventions](./commit-process.md)
35+
3. **Test**: Run linters and tests before pushing
36+
4. **Push**: `git push origin {issue-number}-{description}`
37+
5. **PR**: Create pull request via GitHub
38+
6. **Review**: Address feedback from maintainers
39+
7. **Merge**: Squash and merge when approved
40+
8. **Cleanup**: Delete branch after merge
41+
42+
```bash
43+
# After merge, clean up local branch
44+
git checkout main
45+
git pull origin main
46+
git branch -d 42-add-mysql-support
47+
```
48+
49+
## 🚫 What to Avoid
50+
51+
### Branch Names to Avoid
52+
53+
```bash
54+
# No issue number
55+
git checkout -b add-mysql-support
56+
git checkout -b fix-ssl-issue
57+
58+
# Personal references
59+
git checkout -b jose-feature
60+
git checkout -b my-branch
61+
62+
# Wrong format
63+
git checkout -b issue-42
64+
git checkout -b 42_add_support
65+
git checkout -b 42-Add-MySQL-Support
66+
67+
# Special characters
68+
git checkout -b 42-add@new#feature
69+
```

‎docs/contributing/commit-process.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Commit Process and Pre-commit Checks
2+
3+
This document outlines the commit process, including required pre-commit checks and conventions for the Torrust Testing Infrastructure project.
4+
5+
## 📝 Conventional Commits
6+
7+
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.
8+
9+
### Commit Message Format
10+
11+
```text
12+
<type>[optional scope]: <description>
13+
14+
[optional body]
15+
16+
[optional footer(s)]
17+
```
18+
19+
### Issue Number Convention
20+
21+
When working on a branch with an issue number, include the issue number in your commit messages:
22+
23+
- **Structure**: `{type}: [#{issue}] {description}`
24+
- **Examples**:
25+
26+
```text
27+
feat: [#42] add MySQL database support
28+
fix: [#15] resolve SSL certificate renewal issue
29+
docs: [#8] update deployment guide
30+
ci: [#23] add infrastructure validation tests
31+
```
32+
33+
### Commit Types
34+
35+
| Type | Description | Example |
36+
| ---------- | ------------------------------------- | ------------------------------------------------------ |
37+
| `feat` | New feature or enhancement | `feat: [#42] add LXD container provisioning` |
38+
| `fix` | Bug fix | `fix: [#15] resolve ansible inventory parsing error` |
39+
| `docs` | Documentation changes | `docs: [#8] update installation guide` |
40+
| `style` | Code style changes (formatting, etc.) | `style: [#31] apply rustfmt to all source files` |
41+
| `refactor` | Code refactoring | `refactor: [#45] simplify linting script structure` |
42+
| `test` | Adding or updating tests | `test: [#67] add e2e tests for multipass provisioning` |
43+
| `chore` | Maintenance tasks | `chore: [#89] update dependencies to latest versions` |
44+
| `ci` | CI/CD related changes | `ci: [#23] add workflow for testing provisioning` |
45+
| `perf` | Performance improvements | `perf: [#52] optimize container startup time` |
46+
47+
### Commit Examples
48+
49+
```bash
50+
# Feature addition with issue number
51+
git commit -m "feat: [#42] add support for Ubuntu 22.04 in cloud-init"
52+
53+
# Bug fix with issue number
54+
git commit -m "fix: [#15] resolve ansible inventory parsing error"
55+
56+
# Documentation update with issue number
57+
git commit -m "docs: [#8] add troubleshooting section to README"
58+
59+
# CI/CD changes with issue number
60+
git commit -m "ci: [#23] add workflow for testing provisioning"
61+
62+
# Bug fix with scope (optional format)
63+
git commit -m "fix(ansible): [#15] correct inventory file path resolution"
64+
65+
# Breaking change with issue number (note the !)
66+
git commit -m "feat!: [#42] change default container provider from multipass to lxd"
67+
68+
# Commit with body and footer including issue reference
69+
git commit -m "feat: [#23] add automated testing workflow
70+
71+
Add GitHub Actions workflow that tests:
72+
- LXD container provisioning
73+
- Multipass VM provisioning
74+
- Ansible playbook execution
75+
76+
Closes #23"
77+
```
78+
79+
## ✅ Pre-commit Checklist
80+
81+
Before committing any changes, you **MUST** complete the following checks:
82+
83+
### 1. Run All Linters
84+
85+
```bash
86+
# Run all linters at once
87+
./scripts/linting/lint.sh all
88+
89+
# Or run individually
90+
./scripts/linting/lint.sh md # Markdown
91+
./scripts/linting/lint.sh yaml # YAML
92+
./scripts/linting/lint.sh clippy # Rust code analysis
93+
./scripts/linting/lint.sh rustfmt # Rust formatting
94+
./scripts/linting/lint.sh shellcheck # Shell scripts
95+
```
96+
97+
**All linters must pass** before committing. Fix any reported issues.
98+
99+
### 2. Run Tests
100+
101+
```bash
102+
# Run Rust unit tests
103+
cargo test
104+
105+
# Run E2E tests (if applicable to your changes)
106+
cargo run --bin e2e-tests wait-cloud-init
107+
```
108+
109+
## 📋 Commit Quality Guidelines
110+
111+
### Good Commits
112+
113+
✅ **Atomic**: Each commit represents one logical change
114+
✅ **Descriptive**: Clear, concise description of what changed
115+
✅ **Tested**: All tests pass
116+
✅ **Linted**: All linters pass
117+
✅ **Conventional**: Follows conventional commit format
118+
119+
### Example of Good Commit History
120+
121+
```text
122+
feat: add LXD container provisioning support
123+
fix: resolve ansible inventory template rendering
124+
docs: update contributing guidelines
125+
test: add unit tests for configuration parsing
126+
refactor: extract common logging utilities
127+
```
128+
129+
### Commits to Avoid
130+
131+
❌ **Too large**: Multiple unrelated changes in one commit
132+
❌ **Vague**: Messages like "fix stuff" or "updates"
133+
❌ **Broken**: Commits that don't build or pass tests
134+
❌ **Non-conventional**: Not following the conventional commit format
135+
136+
### Example of Poor Commit History
137+
138+
```text
139+
fix stuff
140+
WIP
141+
updates
142+
more changes
143+
final fix
144+
actually final fix
145+
```

0 commit comments

Comments
 (0)