From 04e3d980a0698c2900609bb9439980bb05c0e1a5 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 7 Jan 2026 00:25:31 +0800 Subject: [PATCH] docs(contributing): add pull request guideline and add notes about AI assisted contributions --- docs/{ => contributing}/contributing.md | 4 +- docs/{ => contributing}/contributing_tldr.md | 2 + docs/contributing/pull_request.md | 71 ++++++++++++++++++++ mkdocs.yml | 6 +- 4 files changed, 79 insertions(+), 4 deletions(-) rename docs/{ => contributing}/contributing.md (96%) rename docs/{ => contributing}/contributing_tldr.md (97%) create mode 100644 docs/contributing/pull_request.md diff --git a/docs/contributing.md b/docs/contributing/contributing.md similarity index 96% rename from docs/contributing.md rename to docs/contributing/contributing.md index 827dfc7ac..446410533 100644 --- a/docs/contributing.md +++ b/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. diff --git a/docs/contributing_tldr.md b/docs/contributing/contributing_tldr.md similarity index 97% rename from docs/contributing_tldr.md rename to docs/contributing/contributing_tldr.md index 91f49d1ca..af350d2bb 100644 --- a/docs/contributing_tldr.md +++ b/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 diff --git a/docs/contributing/pull_request.md b/docs/contributing/pull_request.md new file mode 100644 index 000000000..4682496b4 --- /dev/null +++ b/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! πŸŽ‰ diff --git a/mkdocs.yml b/mkdocs.yml index 28c5b9e38..05d14ae62 100644 --- a/mkdocs.yml +++ b/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: