1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
## Contributing to Commitizen
First, thank you for taking the time to contribute! 🎉 Your contributions help make Commitizen better for everyone.
When contributing to Commitizen, we encourage you to:
1. First, check out the [issues](https://github.com/commitizen-tools/commitizen/issues) and [Features we won't add](faq.md#features-we-wont-add) to see if there's already a discussion about the change you wish to make.
2. If there's no discussion, [create an issue](https://github.com/commitizen-tools/commitizen/issues/new) to discuss your proposed changes.
3. Follow our [development workflow](#development-workflow) and guidelines below.
If you're a first-time contributor, please check out issues labeled [good first issue](https://github.com/commitizen-tools/commitizen/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - these are specifically chosen to be beginner-friendly.
## Prerequisites & Setup
### Required Tools
1. **Python Environment**
- Python `>=3.9`
- [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer) `>=2.0.0`
2. **Version Control & Security**
- Git
- Commitizen
- [GPG](https://gnupg.org) for commit signing
- [Installation page](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation)
- For Mac users: `brew install gnupg`
- For Windows users: Download from [Gpg4win](https://www.gpg4win.org/)
- For Linux users: Use your distribution's package manager (e.g., `apt install gnupg` for Ubuntu)
### Getting Started
1. Fork [Commitizen](https://github.com/commitizen-tools/commitizen)
2. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/commitizen.git
cd commitizen
```
3. Add the upstream repository:
```bash
git remote add upstream https://github.com/commitizen-tools/commitizen.git
```
4. Set up the development environment:
```bash
poetry install
```
5. Set up pre-commit hooks:
```bash
poetry setup-pre-commit
```
## Development Workflow
1. **Create a New Branch**
```bash
git switch -c feature/your-feature-name
# or
git switch -c fix/your-bug-fix
```
2. **Make Your Changes**
- Write your code
- Add tests for new functionalities or fixes
- Update documentation if needed
- Follow the existing code style
3. **Testing**
- Run the full test suite: `poetry all`
- Ensure test coverage doesn't drop (we use [CodeCov](https://app.codecov.io/gh/commitizen-tools/commitizen))
- For documentation changes, run `poetry doc` to check for warnings/errors
4. **Committing Changes**
- Use Commitizen to make commits (we follow [conventional commits](https://www.conventionalcommits.org/))
- Example: `cz commit`
5. **Documentation**
- Update `docs/README.md` if needed
- For CLI help screenshots: `poetry doc:screenshots`
- **DO NOT** update `CHANGELOG.md` (automatically generated)
- **DO NOT** update version numbers (automatically handled)
6. **Pull Request**
- Push your changes: `git push origin your-branch-name`
- Create a pull request on GitHub
- Ensure CI checks pass
- Wait for review and address any feedback
## Use of GitHub Labels
* good-first-issue *(issue only)*
* help-wanted
* issue-status: needs-triage *(issue only)* **(default label for issues)**
* issue-status: wont-fix
* issue-status: wont-implement
* issue-status: duplicate
* issue-status: invalid
* issue-status: wait-for-response
* issue-status: wait-for-implementation
* issue-status: pr-created
* pr-status: wait-for-review **(default label for PRs)**
* pr-status: reviewing
* pr-status: wait-for-modification
* pr-status: wait-for-response
* pr-status: ready-to-merge
* needs: test-case *(PR only)*
* needs: documentation *(PR only)*
* type: feature
* type: bug
* type: documentation
* type: refactor
* type: question *(issue only)*
* os: Windows
* os: Linux
* os: macOS
## Issue life cycle
```mermaid
graph TD
input[/issue created/] -->
needs-triage
needs-triage --triage--> close(wont-implement, wont-fix, duplicate, invalid)
needs-triage --triage--> wait-for-implementation
needs-triage --triage--> wait-for-response
wait-for-response --response--> needs-triage
wait-for-implementation --PR-created--> pr-created --PR-merged--> output[/close/]
close --> output[/close/]
```
## Pull request life cycle
```mermaid
flowchart TD
input[/pull request created/] -->
wait-for-review
--start reviewing -->
reviewing
--finish review -->
reviewed{approved}
reviewed --Y-->
wait-for-merge -->
output[/merge/]
reviewed --n-->
require-more-information{require more information}
require-more-information --y-->
wait-for-response
--response-->
require-more-information
require-more-information --n-->
wait-for-modification
--modification-received-->
review
```
|
