docs(contributing.md): improve readability of contributing docs

Author: bearomorphism

docs/contributing.md

@@ -1,32 +1,84 @@
 ## Contributing to commitizen
 
-First of all, thank you for taking the time to contribute! 🎉
+First, thank you for taking the time to contribute! 🎉
 
 When contributing to [commitizen](https://github.com/commitizen-tools/commitizen), please first create an [issue](https://github.com/commitizen-tools/commitizen/issues) to discuss the change you wish to make before making a change.
 
 If you're a first-time contributor, you can check the issues with the [good first issue](https://github.com/commitizen-tools/commitizen/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tag.
 
-## Install before contributing
-
-1. Install [poetry](https://python-poetry.org/) `>=2.0.0`. See the installation [pages](https://python-poetry.org/docs/#installing-with-the-official-installer).
-2. Install [gpg](https://gnupg.org). See the installation [pages](https://gnupg.org/documentation/manuals/gnupg/Installation.html#Installation). For Mac users, you can use [homebrew](https://brew.sh/).
-
-## Before making a pull request
-
-1. Fork [the repository](https://github.com/commitizen-tools/commitizen).
-2. Clone the repository from your GitHub.
-3. Set up the development environment through [poetry](https://python-poetry.org/) (`poetry install`).
-4. Set up the [pre-commit](https://pre-commit.com/) hook (`poetry setup-pre-commit`).
-5. Checkout a new branch and add your modifications.
-6. Add test cases for all your changes.
-   (We use [CodeCov](https://codecov.io/) to ensure our test coverage does not drop.)
-7. Use [commitizen](https://github.com/commitizen-tools/commitizen) to make git commits. We follow [conventional commits](https://www.conventionalcommits.org/).
-8. Run `poetry all` to ensure you follow the coding style and the tests pass.
-9. Optionally, update the `./docs/README.md` or `docs/images/cli_help` (by running `poetry doc:screenshots`).
-10. **Do not** update the `CHANGELOG.md`; it will be automatically created after merging to `master`.
-11. **Do not** update the versions in the project; they will be automatically updated.
-12. If your changes are about documentation, run `poetry doc` to serve documentation locally and check whether there are any warnings or errors.
-13. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏
+## 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 functionality
+    - 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://codecov.io/))
+    - 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
 
@@ -57,7 +109,7 @@ If you're a first-time contributor, you can check the issues with the [good firs
 * os: macOS
 
 
-### Issue life cycle
+## Issue life cycle
 
 ```mermaid
 graph TD
@@ -75,7 +127,7 @@ graph TD
     close --> output[/close/]
 ```
 
-### Pull request life cycle
+## Pull request life cycle
 
 ```mermaid
 flowchart TD
@@ -103,6 +155,3 @@ flowchart TD
     --modification-received-->
     review
 ```
-
-
-[conventional-commits]: https://www.conventionalcommits.org/