Merge pull request #1153 from RonnyPfannschmidt/documentation-fixups

implement documentation fixups

Author: RonnyPfannschmidt

CHANGELOG.md

@@ -6,19 +6,24 @@
 
 - add `setuptools-scm` console_scripts entry point to make the CLI directly executable
 - make Mercurial command configurable by environment variable `SETUPTOOLS_SCM_HG_COMMAND`
+- fix #1099 use file modification times for dirty working directory timestamps instead of current time
 
 ### Changed
 
 - add `pip` to test optional dependencies for improved uv venv compatibility
 - migrate to selectable entrypoints for better extensibility
 - improve typing for entry_points
+- refactor file modification time logic into shared helper function for better maintainability
+- reduce complexity of HgWorkdir.get_meta method by extracting focused helper methods
 
 ### Fixed
 
 - fix #1145: ensure GitWorkdir.get_head_date returns consistent UTC dates regardless of local timezone
 - fix #687: ensure calendar versioning tests use consistent time context to prevent failures around midnight in non-UTC timezones
 - reintroduce Python 3.9 entrypoints shim for compatibility
 - fix #1136: update customizing.md to fix missing import
+- fix #1001: document the missing version schemes and add examples in the docs
+- fix #1115: explicitly document file finder behaviour
 
 ## v8.3.1
 

README.md

@@ -17,6 +17,8 @@ files that are managed by the SCM
 Unwanted files must be excluded via `MANIFEST.in`
 or [configuring Git archive][git-archive-docs].
 
+> **⚠️ Important:** Installing setuptools-scm automatically enables a file finder that includes **all SCM-tracked files** in your source distributions. This can be surprising if you have development files tracked in Git/Mercurial that you don't want in your package. Use `MANIFEST.in` to exclude unwanted files. See the [documentation] for details.
+
 ## `pyproject.toml` usage
 
 The preferred way to configure [setuptools-scm] is to author

docs/config.md

@@ -152,6 +152,66 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 
 
 
+## automatic file inclusion
+
+!!! warning "Setuptools File Finder Integration"
+
+    `setuptools-scm` automatically registers a setuptools file finder that includes all SCM-tracked files in source distributions. This behavior is **always active** when setuptools-scm is installed, regardless of whether you use it for versioning.
+
+**How it works:**
+
+`setuptools-scm` provides a `setuptools.file_finders` entry point that:
+
+1. Automatically discovers SCM-managed files (Git, Mercurial)
+2. Includes them in source distributions (`python -m build --sdist`)
+3. Works for `include_package_data = True` in package building
+
+**Entry point registration:**
+```toml
+[project.entry-points."setuptools.file_finders"]
+setuptools_scm = "setuptools_scm._file_finders:find_files"
+```
+
+**Files included by default:**
+- All files tracked by Git (`git ls-files`)
+- All files tracked by Mercurial (`hg files`)
+- Includes: source code, documentation, tests, config files, etc.
+- Excludes: untracked files, files in `.gitignore`/`.hgignore`
+
+**Controlling inclusion:**
+
+Use `MANIFEST.in` to override the automatic behavior:
+
+```text title="MANIFEST.in"
+# Exclude development files
+exclude .pre-commit-config.yaml
+exclude tox.ini
+global-exclude *.pyc __pycache__/
+
+# Exclude entire directories
+prune docs/
+prune testing/
+
+# Include non-SCM files
+include data/important.json
+```
+
+**Debugging file inclusion:**
+
+```bash
+# List files that will be included
+python -m setuptools_scm ls
+
+# Build and inspect sdist contents
+python -m build --sdist
+tar -tzf dist/package-*.tar.gz
+```
+
+!!! note "Cannot be disabled"
+
+    The file finder cannot be disabled through configuration - it's automatically active when setuptools-scm is installed. If you need to disable it completely, you must remove setuptools-scm from your build environment (which also means you can't use it for versioning).
+
+
 ## api reference
 
 ### constants

docs/extending.md

@@ -53,9 +53,41 @@ representing the version.
 `guess-next-dev (default)`
 :   Automatically guesses the next development version (default).
     Guesses the upcoming release by incrementing the pre-release segment if present,
-    otherwise by incrementing the micro segment. Then appends :code:`.devN`.
+    otherwise by incrementing the micro segment. Then appends `.devN`.
     In case the tag ends with `.dev0` the version is not bumped
-    and custom `.devN` versions will trigger a error.
+    and custom `.devN` versions will trigger an error.
+
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.1.dev0` (if dirty or distance > 0)
+    - Tag `1.0.0` → version `1.0.0` (if exact match)
+
+`calver-by-date`
+:   Calendar versioning scheme that generates versions based on dates.
+    Uses the format `YY.MM.DD.patch` or `YYYY.MM.DD.patch` depending on the existing tag format.
+    If the commit is on the same date as the latest tag, increments the patch number.
+    Otherwise, uses the current date with patch 0. Supports branch-specific versioning
+    for release branches.
+
+    **Examples:**
+    - Tag `23.01.15.0` on same day → version `23.01.15.1.devN`
+    - Tag `23.01.15.0` on different day (e.g., 2023-01-16) → version `23.01.16.0.devN`
+    - Tag `2023.01.15.0` → uses 4-digit year format for new versions
+
+`no-guess-dev`
+:   Does no next version guessing, just adds `.post1.devN`.
+    This is the recommended replacement for the deprecated `post-release` scheme.
+
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.0.post1.devN` (if distance > 0)
+    - Tag `1.0.0` → version `1.0.0` (if exact match)
+
+`only-version`
+:   Only use the version from the tag, as given.
+
+    !!! warning "This means version is no longer pseudo unique per commit"
+
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.0` (always, regardless of distance or dirty state)
 
 `post-release (deprecated)`
 :   Generates post release versions (adds `.postN`)
@@ -64,6 +96,9 @@ representing the version.
 
     !!! warning "the recommended replacement is `no-guess-dev`"
 
+    **Examples:**
+    - Tag `1.0.0` → version `1.0.0.postN` (where N is the distance)
+
 `python-simplified-semver`
 :   Basic semantic versioning.
 
@@ -73,6 +108,10 @@ representing the version.
 
     This scheme is not compatible with pre-releases.
 
+    **Examples:**
+    - Tag `1.0.0` on non-feature branch → version `1.0.1.devN`
+    - Tag `1.0.0` on feature branch → version `1.1.0.devN`
+
 `release-branch-semver`
 :   Semantic versioning for projects with release branches.
     The same as `guess-next-dev` (incrementing the pre-release or micro segment)
@@ -81,14 +120,9 @@ representing the version.
     non-release branch, increments the minor segment and sets the micro segment to
     zero, then appends `.devN`
 
-`no-guess-dev`
-: Does no next version guessing, just adds `.post1.devN`
-
-`only-version`
-:   Only use the version from the tag, as given.
-
-    !!! warning "This means version is no longer pseudo unique per commit"
-
+    **Examples:**
+    - Tag `1.0.0` on release branch `release-1.0` → version `1.0.1.devN`
+    - Tag `1.0.0` on development branch → version `1.1.0.devN`
 
 ### `setuptools_scm.local_scheme`
 Configures how the local part of a version is rendered given a

docs/index.md

@@ -10,6 +10,16 @@ files that are managed by the SCM
 Unwanted files must be excluded via `MANIFEST.in`
 or [configuring Git archive][git-archive-docs].
 
+!!! warning "Automatic File Inclusion Behavior"
+
+    **Important:** Simply installing `setuptools-scm` as a build dependency will automatically enable its file finder, which includes **all SCM-tracked files** in your source distributions. This happens even if you're not using setuptools-scm for versioning.
+
+    - ✅ **Expected**: All Git/Mercurial tracked files will be included in your sdist
+    - ⚠️ **Surprise**: This includes development files, configs, tests, docs, etc.
+    - 🛠️ **Control**: Use `MANIFEST.in` to exclude unwanted files
+
+    See the [File Finder Documentation](usage.md#file-finders-hook-makes-most-of-manifestin-unnecessary) for details.
+
 [git-archive-docs]: usage.md#builtin-mechanisms-for-obtaining-version-numbers
 
 ## Basic usage

docs/usage.md

@@ -285,17 +285,77 @@ be kept in version control. It's strongly recommended to be put into gitignore.
 
 ### File finders hook makes most of `MANIFEST.in` unnecessary
 
+!!! warning "Automatic File Inclusion"
+
+    **`setuptools-scm` automatically provides a setuptools file finder by default.** This means that when you install setuptools-scm, it will automatically include **all SCM-tracked files** in your source distributions (sdist) without requiring a `MANIFEST.in` file.
+
+    This automatic behavior can be surprising if you're not expecting it. The file finder is active as soon as setuptools-scm is installed in your build environment.
+
 `setuptools-scm` implements a [file_finders] entry point
 which returns all files tracked by your SCM.
 This eliminates the need for a manually constructed `MANIFEST.in` in most cases where this
-would be required when not using `setuptools-scm`, namely:
+would be required when not using `setuptools-scm`.
+
+[file_finders]: https://setuptools.pypa.io/en/stable/userguide/extension.html
+
+#### How it works
+
+1. **Automatic Discovery**: When building source distributions (`python -m build --sdist`), setuptools automatically calls the `setuptools-scm` file finder
+2. **SCM Integration**: The file finder queries your SCM (Git/Mercurial) for all tracked files
+3. **Inclusion**: All tracked files are automatically included in the sdist
+
+#### Controlling file inclusion
+
+**To exclude unwanted files:**
+
+1. **Use `MANIFEST.in`** to exclude specific files/patterns:
+   ```
+   exclude development.txt
+   recursive-exclude tests *.pyc
+   ```
+
+2. **Configure Git archive** (for Git repositories):
+   ```bash
+   # Add to .gitattributes
+   tests/ export-ignore
+   *.md export-ignore
+   ```
+
+3. **Use `.hgignore`** or **Mercurial archive configuration** (for Mercurial repositories)
+
+#### Troubleshooting
+
+**Problem: Unwanted files in my package**
+- ✅ **Solution**: Add exclusions to `MANIFEST.in`
+- ✅ **Alternative**: Use Git/Mercurial archive configuration
+
+**Problem: Missing files in package**
+- ✅ **Check**: Are the files tracked in your SCM?
+- ✅ **Solution**: `git add` missing files or override with `MANIFEST.in`
+
+**Problem: File finder not working**
+- ✅ **Check**: Is setuptools-scm installed in your build environment?
+- ✅ **Check**: Are you in a valid SCM repository?
+
+### Timestamps for Local Development Versions
+
+!!! info "Improved Timestamp Behavior"
+
+    When your working directory has uncommitted changes (dirty), setuptools-scm now uses the **actual modification time of changed files** instead of the current time for local version schemes like `node-and-date`.
+
+    **Before**: Dirty working directories always used current time (`now`)
+    **Now**: Uses the latest modification time of changed files, falling back to current time only if no changed files are found
+
+    This provides more stable and meaningful timestamps that reflect when you actually made changes to your code.
+
+**How it works:**
 
-* To ensure all relevant files are packaged when running the `sdist` command.
-  * When using [include_package_data] to include package data as part of the `build` or `bdist_wheel`.
+1. **Clean repository**: Uses commit timestamp from SCM
+2. **Dirty repository**: Uses latest modification time of changed files
+3. **Fallback**: Uses current time if no modification times can be determined
 
-`MANIFEST.in` may still be used: anything defined there overrides the hook.
-This is mostly useful to exclude files tracked in your SCM from packages,
-although in principle it can be used to explicitly include non-tracked files too.
+**Benefits:**
 
-[file_finders]: https://setuptools.pypa.io/en/latest/userguide/extension.html#adding-support-for-revision-control-systems
-[include_package_data]: https://setuptools.readthedocs.io/en/latest/setuptools.html#including-data-files
+- More stable builds during development
+- Timestamps reflect actual change times
+- Better for reproducible development workflows

pyproject.toml

@@ -49,7 +49,7 @@ dependencies = [
 ]
 [project.optional-dependencies]
 docs = [
-  "entangled-cli~=2.0",
+  #"entangled-cli~=2.0",
   "mkdocs",
   "mkdocs-entangled-plugin",
   "mkdocs-include-markdown-plugin",

src/setuptools_scm/_file_finders/hg.py

@@ -7,19 +7,17 @@
 from .. import _types as _t
 from .._file_finders import is_toplevel_acceptable
 from .._file_finders import scm_find_files
-from .._run_cmd import run as _run
+from ..hg import run_hg
 from ..integration import data_from_mime
 from .pathtools import norm_real
 
 log = logging.getLogger(__name__)
 
-HG_COMMAND = os.environ.get("SETUPTOOLS_SCM_HG_COMMAND", "hg")
-
 
 def _hg_toplevel(path: str) -> str | None:
     try:
-        return _run(
-            [HG_COMMAND, "root"],
+        return run_hg(
+            ["root"],
             cwd=(path or "."),
             check=True,
         ).parse_success(norm_real)
@@ -34,7 +32,7 @@ def _hg_toplevel(path: str) -> str | None:
 def _hg_ls_files_and_dirs(toplevel: str) -> tuple[set[str], set[str]]:
     hg_files: set[str] = set()
     hg_dirs = {toplevel}
-    res = _run([HG_COMMAND, "files"], cwd=toplevel)
+    res = run_hg(["files"], cwd=toplevel)
     if res.returncode:
         return set(), set()
     for name in res.stdout.splitlines():

src/setuptools_scm/git.py

@@ -26,6 +26,7 @@
 from ._run_cmd import run as _run
 from .integration import data_from_mime
 from .scm_workdir import Workdir
+from .scm_workdir import get_latest_file_mtime
 from .version import ScmVersion
 from .version import meta
 from .version import tag_to_version
@@ -144,6 +145,28 @@ def parse_timestamp(timestamp_text: str) -> date | None:
             error_msg="logging the iso date for head failed",
         )
 
+    def get_dirty_tag_date(self) -> date | None:
+        """Get the latest modification time of changed files in the working directory.
+
+        Returns the date of the most recently modified file that has changes,
+        or None if no files are changed or if an error occurs.
+        """
+        if not self.is_dirty():
+            return None
+
+        try:
+            # Get list of changed files
+            changed_files_res = run_git(["diff", "--name-only"], self.path)
+            if changed_files_res.returncode != 0:
+                return None
+
+            changed_files = changed_files_res.stdout.strip().split("\n")
+            return get_latest_file_mtime(changed_files, self.path)
+
+        except Exception as e:
+            log.debug("Failed to get dirty tag date: %s", e)
+            return None
+
     def is_shallow(self) -> bool:
         return self.path.joinpath(".git/shallow").is_file()
 
@@ -277,7 +300,20 @@ def _git_parse_inner(
             tag=tag, distance=distance, dirty=dirty, node=node, config=config
         )
     branch = wd.get_branch()
-    node_date = wd.get_head_date() or datetime.now(timezone.utc).date()
+    node_date = wd.get_head_date()
+
+    # If we can't get node_date from HEAD (e.g., no commits yet),
+    # and the working directory is dirty, try to use the latest
+    # modification time of changed files instead of current time
+    if node_date is None and wd.is_dirty():
+        dirty_date = wd.get_dirty_tag_date()
+        if dirty_date is not None:
+            node_date = dirty_date
+
+    # Final fallback to current time
+    if node_date is None:
+        node_date = datetime.now(timezone.utc).date()
+
     return dataclasses.replace(version, branch=branch, node_date=node_date)