Skip to content

Commit f29fc73

Browse files
bearomorphismbearomorphism
committed
docs(contributing): add pull request guideline and add notes about AI assisted contributions
1 parent de24815 commit f29fc73

File tree

5 files changed

+106
-13
lines changed

5 files changed

+106
-13
lines changed

‎.github/pull_request_template.md‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,19 @@ Please fill in the following content to let us know better about this change.
99

1010
## Checklist
1111

12-
- [ ] I have read the [contributing guidelines](https://commitizen-tools.github.io/commitizen/contributing/)
12+
- [ ] I have read the [contributing guidelines](https://commitizen-tools.github.io/commitizen/contributing/contributing)
13+
14+
### Was generative AI tooling used to co-author this PR?
15+
16+
<!--
17+
If generative AI tooling has been used in the process of authoring this PR, please change below checkbox to `[X]` followed by the name of the tool, uncomment the "Generated-by".
18+
-->
19+
20+
- [ ] Yes (please specify the tool below)
21+
22+
<!--
23+
Generated-by: [Tool Name] following [the guidelines](http://commitizen-tools.github.io/commitizen/contributing/pull_request/#ai-assisted-contributions)
24+
-->
1325

1426
### Code Changes
1527

@@ -23,25 +35,31 @@ Please fill in the following content to let us know better about this change.
2335
- [ ] Update the documentation for the changes
2436

2537
### Documentation Changes
38+
<!-- You can skip this section if you are not making any documentation changes -->
39+
2640

2741
- [ ] Run `uv run poe doc` locally to ensure the documentation pages renders correctly
28-
- [ ] Check and fix any broken links (internal or external) in the documentation
42+
- [ ] Check and fix any broken links (internal or external)
2943

30-
> When running `uv run poe doc`, any broken internal documentation links will be reported in the console output like this:
31-
>
32-
> ```text
33-
> INFO - Doc file 'config.md' contains a link 'commands/bump.md#-post_bump_hooks', but the doc 'commands/bump.md' does not contain an anchor '#-post_bump_hooks'.
34-
> ```
44+
<!--
45+
When running `uv run poe doc`, any broken internal documentation links will be reported in the console output like this:
46+
47+
```text
48+
INFO - Doc file 'config.md' contains a link 'commands/bump.md#-post_bump_hooks', but the doc 'commands/bump.md' does not contain an anchor '#-post_bump_hooks'.
49+
```
50+
-->
3551

3652
## Expected Behavior
3753
<!-- A clear and concise description of what you expected to happen -->
3854

3955

4056
## Steps to Test This Pull Request
41-
<!-- Steps to reproduce the behavior:
57+
<!--
58+
Steps to reproduce the behavior:
4259
1. ...
4360
2. ...
44-
3. ... -->
61+
3. ...
62+
-->
4563

4664

4765
## Additional Context

docs/contributing.md renamed to docs/contributing/contributing.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
## Contributing to Commitizen
1+
# Contributing to Commitizen
22

33
First, thank you for taking the time to contribute! 🎉 Your contributions help make Commitizen better for everyone.
44

55
When contributing to Commitizen, we encourage you to:
66

7-
1. First, check out the [issues](https://github.com/commitizen-tools/commitizen/issues) and [Features we won't add](features_wont_add.md) to see if there's already a discussion about the change you wish to make.
7+
1. First, check out the [issues](https://github.com/commitizen-tools/commitizen/issues) and [Features we won't add](../features_wont_add.md) to see if there's already a discussion about the change you wish to make.
88
2. If there's no discussion, [create an issue](https://github.com/commitizen-tools/commitizen/issues/new) to discuss your proposed changes.
99
3. Follow our [development workflow](#development-workflow) and guidelines below.
1010

docs/contributing_tldr.md renamed to docs/contributing/contributing_tldr.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Contributing TL;DR
2+
13
Feel free to send a PR to update this file if you find anything useful. 🙇
24

35
## Environment

‎docs/contributing/pull_request.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Pull Request Guidelines
2+
3+
This document outlines important guidelines to follow when creating a pull request.
4+
5+
## Before Creating a Pull Request
6+
7+
1. **Check Existing Issues**: Ensure there's a related issue or discussion for your changes. If not, create one first to discuss the proposed changes.
8+
2. **Follow the Development Workflow**: Make sure you've followed all steps in the [contributing guidelines](contributing.md).
9+
10+
## Making Changes
11+
12+
When adding new code, match the existing coding style in the file you're modifying. Consistency within a file and throughout the project is crucial for maintainability.
13+
14+
## Following PR Description Template Instructions
15+
16+
The PR description template includes a checklist and specific requirements. Please:
17+
18+
1. **Complete the Checklist**: Check off all applicable items before requesting review.
19+
2. **Provide Clear Descriptions**: Clearly describe what the change does, expected behavior, and steps to test.
20+
3. **Respond to Feedback**: Carefully read maintainer feedback and address all points raised. Ask for clarification if something is unclear.
21+
22+
## AI-Assisted Contributions
23+
24+
We welcome contributions that use AI tools for assistance, but we have strict quality standards to maintain code quality and avoid "AI spaghetti code."
25+
26+
!!! note
27+
Most of our new documentation changes are, of course, generated by AI, but we still need to review it and make sure it's correct.
28+
29+
![when bro's code is filled with "🔥 🚀 💥 ❌ ✅"](https://images3.memedroid.com/images/UPLOADED78/69501f1c23cab.webp)
30+
31+
### Guidelines for AI-Assisted PRs
32+
33+
1. **Review and Refine**: Thoroughly review and understand all AI-generated code. Refactor to match our project's style and remove unnecessary complexity.
34+
2. **Test Thoroughly**: Don't assume AI-generated code works—test it extensively with comprehensive test cases and manual testing when possible.
35+
3. **Understand the Code**: You should be able to explain every line. If you don't understand something, learn about it or rewrite it. Maintainers may ask you to explain your code.
36+
4. **Avoid Common Pitfalls**:
37+
- Over-engineering (simplify when possible)
38+
- Inconsistent style (ensure consistency with our standards)
39+
- Unnecessary dependencies
40+
- Copy-paste without adaptation
41+
- Verbose or obvious comments
42+
5. **Code Quality Still Matters**: AI assistance doesn't excuse poor code quality. All code must pass linting, type checking, and follow best practices.
43+
6. **Be Transparent**: **Mention AI assistance in the PR description**. Code quality standards remain the same regardless of how the code was written.
44+
45+
!!! warning "Consequences of Poor AI-Assisted Contributions"
46+
Maintainers who identify low-quality AI-generated code or copy-pasted responses will have no choice but to close the related PRs. This adds unnecessary burden on maintainers and doesn't help the project. Additionally, the contributor's reputation is impacted as maintainers may lose confidence and might restrict the user from making further contributions.
47+
48+
### What We Consider "AI Spaghetti"
49+
50+
Red flags that may result in PR rejection or requests for significant refactoring:
51+
52+
- Overly complex solutions when simpler ones exist
53+
- Unnecessary abstractions or design patterns
54+
- Code that's difficult to understand or maintain
55+
- Missing or inadequate tests
56+
- Copy-pasted code blocks that don't fit the project structure
57+
- Excessive comments explaining obvious things
58+
59+
**Remember**: If you use AI tools, you're still responsible for the quality of the final code. Use AI as a starting point, not a final solution.
60+
61+
## Commenting on the PR
62+
63+
When commenting on the PR:
64+
65+
- Address the feedback points raised by maintainers
66+
- Ask questions if something is unclear
67+
- **Do not** just copy-paste AI-generated responses
68+
- Maintainers want to see your thought process and understanding of the codebase
69+
- Maintainers and other contributors can tell if you're just copying and pasting AI-generated responses
70+
71+
Thank you for helping make Commitizen better! 🎉

‎mkdocs.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,8 +83,10 @@ nav:
8383
- "third-party-plugins/cz-legacy.md"
8484
- "third-party-plugins/cz-path.md"
8585
- "third-party-plugins/github-jira-conventional.md"
86-
- Contributing: "contributing.md"
87-
- Contributing TL;DR: "contributing_tldr.md"
86+
- Contributing:
87+
- "contributing/contributing.md"
88+
- "contributing/contributing_tldr.md"
89+
- "contributing/pull_request.md"
8890
- "history.md"
8991
- Resources: "external_links.md"
9092

0 commit comments

Comments
 (0)