docs(contributing): add pull request guideline and add notes about AI assisted contributions

docs/contributing.md → docs/contributing/contributing.md

@@ -1,10 +1,10 @@
-## Contributing to Commitizen
+# 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](features_wont_add.md) to see if there's already a discussion about the change you wish to make.
+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.
 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.
 

docs/contributing_tldr.md → docs/contributing/contributing_tldr.md

@@ -1,3 +1,5 @@
+# Contributing TL;DR
+
 Feel free to send a PR to update this file if you find anything useful. 🙇
 
 ## Environment

docs/contributing/pull_request.md

@@ -0,0 +1,71 @@
+# Pull Request Guidelines
+
+This document outlines important guidelines to follow when creating a pull request.
+
+## Before Creating a Pull Request
+
+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.
+2. **Follow the Development Workflow**: Make sure you've followed all steps in the [contributing guidelines](contributing.md).
+
+## Making Changes
+
+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.
+
+## Following PR Description Template Instructions
+
+The PR description template includes a checklist and specific requirements. Please:
+
+1. **Complete the Checklist**: Check off all applicable items before requesting review.
+2. **Provide Clear Descriptions**: Clearly describe what the change does, expected behavior, and steps to test.
+3. **Respond to Feedback**: Carefully read maintainer feedback and address all points raised. Ask for clarification if something is unclear.
+
+## AI-Assisted Contributions
+
+We welcome contributions that use AI tools for assistance, but we have strict quality standards to maintain code quality and avoid "AI spaghetti code."
+
+!!! note
+    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.
+
+![when bro's code is filled with "🔥 🚀 💥 ❌ ✅"](https://images3.memedroid.com/images/UPLOADED78/69501f1c23cab.webp)
+
+### Guidelines for AI-Assisted PRs
+
+1. **Review and Refine**: Thoroughly review and understand all AI-generated code. Refactor to match our project's style and remove unnecessary complexity.
+2. **Test Thoroughly**: Don't assume AI-generated code works—test it extensively with comprehensive test cases and manual testing when possible.
+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.
+4. **Avoid Common Pitfalls**:
+    - Over-engineering (simplify when possible)
+    - Inconsistent style (ensure consistency with our standards)
+    - Unnecessary dependencies
+    - Copy-paste without adaptation
+    - Verbose or obvious comments
+5. **Code Quality Still Matters**: AI assistance doesn't excuse poor code quality. All code must pass linting, type checking, and follow best practices.
+6. **Be Transparent**: **Mention AI assistance in the PR description**. Code quality standards remain the same regardless of how the code was written.
+
+!!! warning "Consequences of Poor AI-Assisted Contributions"
+    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.
+
+### What We Consider "AI Spaghetti"
+
+Red flags that may result in PR rejection or requests for significant refactoring:
+
+- Overly complex solutions when simpler ones exist
+- Unnecessary abstractions or design patterns
+- Code that's difficult to understand or maintain
+- Missing or inadequate tests
+- Copy-pasted code blocks that don't fit the project structure
+- Excessive comments explaining obvious things
+
+**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.
+
+## Commenting on the PR
+
+When commenting on the PR:
+
+- Address the feedback points raised by maintainers
+- Ask questions if something is unclear
+- **Do not** just copy-paste AI-generated responses
+    - Maintainers want to see your thought process and understanding of the codebase
+    - Maintainers and other contributors can tell if you're just copying and pasting AI-generated responses
+
+Thank you for helping make Commitizen better! 🎉

mkdocs.yml

@@ -81,8 +81,10 @@ nav:
     - "third-party-plugins/cz-legacy.md"
     - "third-party-plugins/cz-path.md"
     - "third-party-plugins/github-jira-conventional.md"
-  - Contributing: "contributing.md"
-  - Contributing TL;DR: "contributing_tldr.md"
+  - Contributing:
+    - "contributing/contributing.md"
+    - "contributing/contributing_tldr.md"
+    - "contributing/pull_request.md"
   - Resources: "external_links.md"
 
 markdown_extensions: