Update documentation for automatic version resolution and publishing process

This commit enhances the documentation in PUBLISHING.md, USAGE.md, and VERSION_RESOLUTION.md to clarify the automatic version resolution feature based on conventional commits. It details how the tool determines the next version when publishing without a specified version, including behavior for subfolder builds. Additionally, it updates examples and explanations to improve user understanding of version handling and the publishing process.

Author: alelom

docs/PUBLISHING.md

@@ -7,8 +7,9 @@ The package includes built-in support for publishing to PyPI, TestPyPI, and Azur
 Publish after building:
 
 ```bash
-# Publish to PyPI
+# Publish to PyPI (version resolved automatically via conventional commits)
 python-package-folder --publish pypi
+# See [Version Resolution](VERSION_RESOLUTION.md) for details on automatic versioning
 
 # Publish to PyPI with a specific version
 python-package-folder --version "1.2.3" --publish pypi
@@ -41,6 +42,20 @@ python-package-folder --publish pypi --skip-existing
 - **403 Forbidden**: Usually means you used your username instead of `__token__` with an API token. The tool now auto-detects this.
 - **TestPyPI vs PyPI**: TestPyPI requires a separate account and token from https://test.pypi.org/manage/account/token/
 
+## Version Resolution
+
+When publishing without `--version`, the tool automatically resolves the next version using [conventional commits](VERSION_RESOLUTION.md#automatic-version-resolution). This queries the target registry for the latest published version and calculates the next version based on commit messages since that version.
+
+```bash
+# Version resolved automatically from conventional commits
+python-package-folder --publish pypi
+
+# Or specify version explicitly
+python-package-folder --version "1.2.3" --publish pypi
+```
+
+See [Version Resolution](VERSION_RESOLUTION.md) for complete details on how automatic versioning works.
+
 ## Smart File Filtering
 
 When publishing, the tool automatically filters distribution files to only upload those matching the current build:

docs/USAGE.md

@@ -77,7 +77,7 @@ The tool automatically:
 - **For subfolder builds**: Handles `pyproject.toml` configuration:
   - **If `pyproject.toml` exists in subfolder**: 
     - Uses that file (copies it to project root temporarily, adjusting package paths and ensuring `[build-system]` uses hatchling)
-    - **Version handling**: The version in the subfolder's `pyproject.toml` is automatically updated to match the derived version (from conventional commits or `--version` argument). A warning is shown if versions differ.
+    - **Version handling**: The version in the subfolder's `pyproject.toml` is automatically updated to match the derived version (from [conventional commits](VERSION_RESOLUTION.md#automatic-version-resolution) or `--version` argument). A warning is shown if versions differ.
     - **Name handling**: If the subfolder's `pyproject.toml` has a `name` field that differs from the derived name, a warning is shown but the subfolder's name is used (not the derived one).
     - **Dependencies handling**: If the subfolder's `pyproject.toml` has a non-empty `dependencies` field, automatic dependency detection is skipped with a warning. To enable automatic detection, remove or empty the `dependencies` field.
     - **Field merging**: Missing fields (like `description`, `authors`, `keywords`, `classifiers`, `license`, `urls`, etc.) are automatically filled from the parent `pyproject.toml` if available.
@@ -107,7 +107,7 @@ python-package-folder --version "0.1.0" --package-name "my-subfolder-package" --
 python-package-folder --version "0.1.0" --dependency-group "dev" --publish pypi
 
 # If subfolder has its own pyproject.toml, it will be used automatically
-# The version will be updated to match the derived version (from conventional commits)
+# The version will be updated to match the derived version (from [conventional commits](VERSION_RESOLUTION.md#automatic-version-resolution))
 # The package name from the subfolder toml will be used (even if it differs from derived)
 cd src/integration/my_package  # assuming my_package/pyproject.toml exists
 python-package-folder --publish pypi
@@ -117,7 +117,7 @@ python-package-folder --publish pypi
 
 When a subfolder has its own `pyproject.toml`, the tool intelligently merges it with derived information:
 
-1. **Version**: Always updated to match the derived version (from conventional commits or `--version`). If the subfolder's version differs, a warning is shown but the derived version is used.
+1. **Version**: Always updated to match the derived version (from [conventional commits](VERSION_RESOLUTION.md#automatic-version-resolution) or `--version`). If the subfolder's version differs, a warning is shown but the derived version is used.
 
 2. **Name**: If the subfolder's `pyproject.toml` has a `name` field, it takes precedence over the derived name. A warning is shown if they differ.
 

docs/VERSION_RESOLUTION.md

@@ -29,6 +29,13 @@ The `--version` option:
 
 When `--version` is not provided, the tool automatically determines the next version using conventional commits. This is a **Python-native implementation** that follows the same conventions as [semantic-release](https://semantic-release.gitbook.io/semantic-release/) using the Angular preset, but requires no Node.js dependencies.
 
+**When Version Resolution Happens:**
+- Version resolution is triggered when `--version` is **not** provided AND:
+  - You're building a **subfolder** (any directory that's not the main `src/` directory), OR
+  - You're using `--publish` (for main package builds)
+- If `--version` is provided, it is used directly and no resolution is performed
+- If `--analyze-only` is used, version resolution is skipped
+
 **Version Resolution Flow:**
 
 ```mermaid
@@ -48,7 +55,8 @@ flowchart TD
 - **Baseline version**:
   - **Registry Query (Preferred)**: When publishing to a repository (PyPI, TestPyPI, or Azure Artifacts), the tool queries the target registry for the latest published version and uses it as the baseline for version calculation. This ensures version calculations are based on what's actually published, not just git tags.
   - **Git Tags (Fallback)**: If the package doesn't exist on the registry yet (first release) or if registry query fails, the tool falls back to using git tags to determine the starting version.
-- **New version to publish**: After determining the baseline version, the tool analyzes commits since that version to calculate the next version bump (major, minor, or patch) based on [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) messages.
+  - **Default Baseline**: If no registry version or git tags are found, the baseline defaults to `0.0.0` (treating it as a first release)
+- **New version to publish**: After determining the baseline version, the tool analyzes commits since that version to calculate the next version bump (major, minor, or patch) based on [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) messages. If no conventional commits are found but a baseline exists (and it's not `0.0.0`), the tool automatically bumps the minor version.
 
 **For subfolder builds (Workflow 1):**
 - Uses per-package tags: `{package-name}-v{version}` (e.g., `my-package-v1.2.3`)
@@ -112,9 +120,20 @@ python-package-folder --publish pypi
 python-package-folder --publish pypi
 ```
 
+**Version Calculation Behavior:**
+- **With conventional commits**: Version is calculated based on commit types (feat → minor, fix → patch, BREAKING CHANGE → major)
+- **Without conventional commits** (but baseline exists):
+  - If a baseline version exists (from registry or git tags) and it's not `0.0.0`, the tool automatically bumps the **minor version** even if no conventional commits are found
+  - Example: Baseline `1.2.3` with only `docs:` commits → Next version: `1.3.0`
+- **First release** (`0.0.0` baseline):
+  - If any commits exist (even without conventional format), defaults to `0.1.0`
+  - If no commits exist, version resolution fails and `--version` must be provided explicitly
+- **No baseline found**: Version resolution fails and `--version` must be provided explicitly
+
 **Requirements:**
-- Conventional commits (e.g., `fix:`, `feat:`, `BREAKING CHANGE:`) are required for version calculation
-- The tool will fall back to requiring `--version` explicitly if no baseline version is found or no relevant commits are detected
+- A baseline version (from registry or git tags) is required for version calculation, OR
+- For first releases, at least one commit must exist
+- If no baseline is found and no commits exist, `--version` must be provided explicitly
 
 ## Subfolder Versioning