docs(contributing): update docs for setup dev environment and testing

    - docs(readme): mention the tests snapshots as output examples
    - docs(docker-example): add run_command.txt for running demo container

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
         args: ['-f=lf']
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.3
+    rev: v0.6.8
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

CHANGELOG.md

@@ -18,27 +18,16 @@
 
 ### 🐛 Bug fixes
 
-- **changelog**: fix double title, header and footer on 'cz bump' *(Tomas Sebestik - cce3c00)*
+- **changelog**: fix double title, header and footer on 'cz bump' *(Tomas Sebestik - 0b8c6ae)*
 
 ### 📖 Documentation
 
-- **docker-example**: add run_command.txt for running demo container *(Tomas Sebestik - 0fa8c2e)*
+- **contributing**: update docs for setup dev environment and testing *(Tomas Sebestik - 4c88334)*
+- **docker-example**: add run_command.txt for running demo container *(Tomas Sebestik - 4c88334)*
 
 ### 🔧 Code refactoring
 
-- **python-3.9**: refactor syntax and typing for python 3.9 *(Tomas Sebestik - 8de6c1d)*
-
----
-
-## v1.1.0 (2024-09-24)
-
-### 🐛 Bug fixes
-
-- **changelog**: fix double title, header and footer on 'cz bump' *(Tomas Sebestik - f715e63)*
-
-### 📖 Documentation
-
-- **docker-example**: add run_command.txt for running demo container *(Tomas Sebestik - 0fa8c2e)*
+- **python-3.9**: refactor syntax and typing for python 3.9 *(Tomas Sebestik - bb57d37)*
 
 ---
 

CONTRIBUTING.md

@@ -1,66 +1,151 @@
 # Contributing and Development
 
+> \[!NOTE\]
+> This project supports Python 3.9 as the minimum version. All development should be done in the minimum supported version to ensure compatibility.
+> Automated tests should prevent compatibility issues (as they are tested on all versions and platforms), but save yourself potential trouble.
+
 We welcome contributions! To contribute to this repository, please follow these steps:
 
-## Code and Testing
+- [Contributing and Development](#contributing-and-development)
+  - [Development Environment](#development-environment)
+    - [Set Up Development Environment](#set-up-development-environment)
+  - [Code Structure](#code-structure)
+  - [Documentation and Maintenance](#documentation-and-maintenance)
+  - [Testing](#testing)
+    - [Manual Testing](#manual-testing)
+    - [Manual Testing (External Project)](#manual-testing-external-project)
+    - [Automated Testing](#automated-testing)
+  - [Pull Request Guidelines](#pull-request-guidelines)
+
+---
+
+## Development Environment
+
+This project uses the **Just** command runner, which is installed as part of the development dependencies. Run `just` to see the available recipes that you can use.
+
+| Command                  | Description                                                             |
+| ------------------------ | ----------------------------------------------------------------------- |
+| `just install`           | Installs the development environment                                    |
+| `just install-precommit` | Installs and updates the pre-commit hooks environment                   |
+| `just lock-requirements` | Recompiles `requirements.txt` from dev-dependencies in `pyproject.toml` |
+| `just clean`             | Removes caches, builds, reports, and other generated files              |
+| `just build`             | Builds and checks the distribution package                              |
+| `just version`           | Releases version info and lists commits since the last release          |
+| `just test`              | Runs tests with coverage report                                         |
+| `just update-snapshots`  | Updates snapshots (known results) for pytest                            |
+
+Recipes are defined in the `/Justfile`. Feel free to suggest new ones.
+
+### Set Up Development Environment
+
+Clone the repository:
+
+```sh
+git clone https://github.com/espressif/cz-plugin-espressif.git
+```
+
+Create and activate the virtual environment:
+
+```sh
+python -m venv venv && . venv/bin/activate
+```
+
+Install the locally editable Python project with development and test dependencies:
 
-- **Code Style and Structure:**
+```sh
+pip install -e '.[dev,test]'
+```
 
-- **Pre-Commit Hooks:** Install pre-commit hooks in this repository using the `pre-commit install` command.
+Test that the plugin is recognized and responds:
 
-- **Readable Code Structure:** Structure your code in a readable manner. The main logic should be in the default rule function, with implementation details in helper functions. Avoid nested `if` statements and unnecessary `else` statements to maintain code clarity and simplicity.
+```sh
+cz example
+```
 
-- **Remove Debug Statements:** Remove any development debug statements from your files.
+Install pre-commit hooks:
 
-- **Automated Tests:** We aim for full test coverage, so **partial tests will not be accepted**. The tests should cover all typical usage scenarios as well as edge cases to ensure robustness.
+```sh
+just install-precommit
+```
 
-- **Testing Tool:** It is recommended to run `pytest` frequently during development to ensure that all aspects of your code are functioning as expected.
+---
+
+## Code Structure
+
+- **Readable Code Structure:** Keep your code well-organized and readable. The main logic should be placed in the default rule function, while implementation details should be separated into helper functions. Avoid nested `if` statements and unnecessary `else` statements to maintain code clarity and simplicity.
+
+- **Remove Debug Statements:** Ensure that all debug statements are removed before submitting your pull request (PR) for review.
+
+- **Automated Tests:** This project uses a testing strategy that compares the output generated by `commitizen` + this plugin against known and expected snapshots. If you run `pytest --snapshot-update`, it updates the snapshots, adding new ones for new test cases and removing those for deleted tests.
+
+- **Testing Tool:** Run `pytest` frequently during development to ensure your code is functioning as expected.
+
+---
 
 ## Documentation and Maintenance
 
-- **Changelog:** `CHANGELOG.md` is generated automatically by `commitizen` from commit messages. Not need to update `CHANGELOG.md` manually. Focus on informative and clear commit messages which end in the release notes.
+- **Changelog:** The `CHANGELOG.md` is generated automatically using `commitizen` + the `czespressif` plugin from commit messages. There is no need to manually update the changelog. Instead, focus on writing informative and clear commit messages, which will be reflected in the release notes. When possible, include the scope in your commit message.
 
-- **Documentation:** Regularly check and update the documentation to keep it current.
+- **Documentation:** Regularly review and update the documentation to ensure it stays up-to-date.
 
 - **PR/MR Descriptions and Documentation:** When making contributions, clearly describe any changes or new features in both the PR (Pull Request on GitHub) or MR (Merge Request on GitLab) description and the project documentation. If you're modifying the output style, please include a thumbnail of the new style.
 
-## Development and Local Testing
+---
+
+## Testing
 
-1. **Clone the Project**
+This project uses a test strategy comparing the output generated by `commitizen` + the `czespressif` plugin against known and expected snapshots.
 
-- Clone the repository to your local machine using:
+### Manual Testing
+
+Run tests with:
 
 ```sh
-git clone <project_clone_url>
+pytest
 ```
 
-2. **Set Up Development Environment:**
+If you intend to update snapshots (visuals, style), ensure you describe the reason for this change in the GitHub PR description.
 
-- Create and activate a virtual environment:
+Update snapshots with:
 
-  ```sh
-  python -m venv venv && source ./venv/bin/activate
-  ```
+```sh
+pytest --snapshot-update
+```
 
-  or:
+This will update snapshots, adding new ones for new test cases and removing those for deleted tests.
 
-  ```sh
-  virtualenv venv && source ./venv/bin/activate
-  ```
+Before submitting a pull request, ensure your changes pass all the tests. While this project does not aim for 100% test coverage, we are aiming for strong coverage and continually work to improve it. If you add new functionality, it should be reflected and tested appropriately.
+
+### Manual Testing (External Project)
+
+To test this plugin in another project (which must have some git history and tags), run:
+
+```sh
+pip install -e <absolute-path-to-your-local-clone-of-this-project>
+
+```
+
+Next, set the `commitizen` configuration in the `pyproject.toml` of the external project. Once that's done, you can run `commitizen` commands such as `cz changelog` and `cz bump --dry-run` to observe how they modify the changelog.
+
+### Automated Testing
+
+We use a GitHub Workflow to test this plugin across different Python versions (3.9 - 3.12) and platforms (MacOS, Linux, Windows) with every update of Pull Request and when merged to default branch.
+
+---
 
-- Install the project and development dependencies:
+## Pull Request Guidelines
 
-  ```sh
-  pip install -e '.[dev]'
-  ```
+Please ensure that your PR is complete before requesting a review (or switching from Draft to Ready for Review):
 
-3. **Testing Your Changes:**
+- All checks and tests must pass.
+- All DangerJS PR linter warnings must be addressed.
+- Your changes have to be well documented.
+- If you've added new functionality, please describe why it’s useful and how it was tested.
 
-- Before submitting a pull request, ensure your changes pass all the tests. You can run the test suite with the following command:
+There is a Pull Request template to help guide you in writing a proper PR description.
 
-  ```sh
-  pytest
-  ```
+> \[!IMPORTANT\]
+> Incomplete PRs can't be reviewed — please be respectful of the reviewers' time and avoid submitting incomplete work.
 
 ---
 

Justfile

@@ -36,6 +36,12 @@ gitstyle := '%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s
     pip install --require-virtualenv --upgrade pip
 
 
+# PROJECT: Install and update pre-commit hooks
+@install-precommit:
+    pre-commit install
+    pre-commit autoupdate
+
+
 # PROJECT: Re-compile requirements.txt from dev-dependencies in pyproject.toml
 @lock-requirements:
     pip-compile --strip-extras --output-file=requirements.txt pyproject.toml > /dev/null
@@ -67,14 +73,7 @@ gitstyle := '%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s
     twine check dist/*
 
 
-# PROJECT:
-@bump-test:
-    clear
-    pre-commit run --all-files
-    cz bump --dry-run
-
-
-# PYTEST: Run tests with coverage report
+## PYTEST: Run tests with coverage report
 @test:
     pytest
 
@@ -117,40 +116,3 @@ gitstyle := '%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s
 @rebase base="master":
     git fetch origin {{base}}
     git rebase -i origin/{{base}}
-
-
-# ----------------------------------------------
-
-@generate-cz-bump:
-    clear
-    cz bump --dry-run | tee "output/cz-bump.test.md"
-
-
-@generate-cz-example:
-    clear
-    cz example | tee "output/cz-example.test.md"
-
-
-@generate-cz-info:
-    clear
-    cz info | tee "output/cz-info.test.md"
-
-
-@generate-cz-schema:
-    clear
-    cz schema | tee "output/cz-schema.test.md"
-
-
-@generate-changelog:
-    clear
-    cz changelog --dry-run | tee "output/CHANGELOG.test.md"
-
-
-@generate-changelog-incremental:
-    clear
-    cz changelog --incremental --dry-run | tee "output/CHANGELOG-incremental.test.md"
-
-
-@generate-release-notes:
-    clear
-    cz changelog v1.1.0 --template="RELEASE_NOTES.md.j2" --dry-run | tee "output/RELEASE_NOTES.test.md"

README.md

@@ -52,7 +52,7 @@ All of this with minimal config and setup, so your `pyproject.toml` file stays c
     - [Optimal setup](#optimal-setup)
     - [Additional configurable parameters](#additional-configurable-parameters)
   - [Solving Troubles](#solving-troubles)
-  - [Pre-commit hook](#pre-commit-hook)
+  - [Pre-commit hook (beta)](#pre-commit-hook-beta)
   - [Contributing](#contributing)
   - [License](#license)
   - [Credits](#credits)
@@ -107,12 +107,18 @@ cz example
 > commitizen itself is in the plugin's dependencies, so pip will take care of everything.
 
 > \[!WARNING\]
-> Don't try to install it system-wide with `pipx`, it probably not going to work as you expect.
+> Don't try to install it system-wide with `pipx`; it likely won't work as expected.
+> (This option will be explored in the future, and once a solution is found, we will update this recommendation.)
 
 ---
 
 ## Usage
 
+> \[!TIP\]
+> You can check the implementation of this command in the GitHub workflow [.github/workflows/create-release.yml](.github/workflows/create-release.yml) if you're interested.
+> In this project's [tests/**snapshots**/test_changelog/](tests/__snapshots__/test_changelog/) directory, we store snapshots used for automated testing. These snapshots **also serve as examples of the plugin's output**.
+> You can explore them and compare the plugin output (`test_changelog_czespressif_*.md`) with the default Commitizen output (`test_changelog_cz_default_*.md`), which is generated when our plugin is not used.
+
 ### Create Changelog file
 
 If a changelog already exists in your project, make sure you have staged or committed its latest version.
@@ -205,22 +211,22 @@ Config is accepted in `pyproject.toml` (priority, following example), `.cz.toml`
 
 ```ini
 [tool.commitizen]
-   name            = "czespressif"
-   bump_message    = 'change(bump): release $current_version → $new_version [skip-ci]'
+   name                      = "czespressif"
+   bump_message              = 'change(bump): release $current_version → $new_version [skip-ci]'
 ```
 
 ### Optimal setup
 
 ```ini
 [tool.commitizen]
-  name            = "czespressif"
-  bump_message    = 'change(bump): release $current_version → $new_version [skip-ci]'
+  name                       = "czespressif"
+  bump_message               = 'change(bump): release $current_version → $new_version [skip-ci]'
 
   # see commitizen docs, following are standard configs
-  annotated_tag = true
+  annotated_tag              = true
   changelog_merge_prerelease = true
-  tag_format = "v$version"
-  update_changelog_on_bump = true
+  tag_format                 = "v$version"
+  update_changelog_on_bump   = true
   version                    = "1.2.3"
   version_files              = ["<src>/__init__.py:__version__"]
   version_provider           = "commitizen"
@@ -355,7 +361,7 @@ fi
 
 ---
 
-## Pre-commit hook
+## Pre-commit hook (beta)
 
 To automatically keep your changelog's "Unreleased" section up to date, add the following to your `.pre-commit-config.yaml` file:
 

docker/run_command.txt

@@ -0,0 +1 @@
+docker run --rm -v $(pwd):/app -u $(id -u):$(id -g) tomasad/czespressif-demo

pyproject.toml

@@ -84,7 +84,7 @@
     warn_return_any        = true
 
 [tool.pytest.ini_options]
-    addopts   = "--log-cli-level DEBUG --cov=czespressif --cov-report=term"
+    addopts   = "-s --log-cli-level DEBUG --cov=czespressif --cov-report=term"
     markers   = ["settings: mark test to use custom czespressif settings from pyproject.toml"]
     testpaths = "tests"