main: Better Reporting of the GUI Tool Version Numbers

[joshanne]

This is hopefully a change for the better.

I have team members running various versions of the main branch since the last release. I cannot tell exactly which version they are running because the application only tells me what version.py contains, which is typically updated just before the next tag and release is about to occur.

This PR makes use of setuptools_scm to improve the reporting of the version number.

The current build/release process entails:

1. Change the software version in version.py
2. Tag the release
3. Build and generate the release artifacts

This means, for all users installing from master after the last release, their build "looks" like the most recent release, but does not indicate that it is development patches on top of the last release.

This PR aims to improve some of that reporting.

Currently outstanding:

• Version Generation Working as expected on:
  • Linux
    • AppImage Generation (PR build: add linuxbuild.sh to generate an AppImage file for portable distribution #138)
    • Python Wheel Generation
    • Python Run From Folder
  • Windows
    • MSI Generation
    • Python Run From Folder
    • Python Wheel
  • macOS
    • DMG Generation
    • Python Run From Folder
    • Python Wheel

All of this assumes the user has installed dronecan_gui_tool with one of the following methods:

pipx install .
python -m pip install .
uv pip install .
pipx install git+https://github.com/dronecan/gui_tool.git
python -m pip install git+https://github.com/dronecan/gui_tool.git
uv pip install git+https://github.com/dronecan/gui_tool.git

After which, one of the following outcomes occur...

# Release Version installed, check the version...

$> dronecan_gui_tool --version
DroneCAN GUI Tool is an application for DroneCAN bus management and diagnostics
DroneCAN GUI Tool Version: 4.3.2

# Clean Working Tree Version Installed, but not a tagged commit...
$> dronecan_gui_tool --version
DroneCAN GUI Tool is an application for DroneCAN bus management and diagnostics
DroneCAN GUI Tool Version: 1.2.28
Development Build: post43.g9f9737e40

# Dirty Working Tree Version installed, not tagged commit
$> dronecan_gui_tool --version
DroneCAN GUI Tool is an application for DroneCAN bus management and diagnostics
DroneCAN GUI Tool Version: 1.2.28
Development Build: post44.g4fba222d7.d20260724
Warning: Built from a dirty working tree!

Similarly, the version can be seen in the application.

Release Build:

Clean Work Tree, Development Build

Dirty Work Tree, Development Build

When locally running the build, you will now get the following:

$> ./bin/dronecan_gui_tool --version
Running from the source directory
DroneCAN GUI Tool is an application for DroneCAN bus management and diagnostics
DroneCAN GUI Tool Version: 1.2.28
Development Build: source-post45.g69793c2

I'm in the process of updating README.md - If this is accepted, the new Release Workflow should be updated to something like:

1. Create the Tag for the new version.
2. Push tag to repo
3. Build and release artifacts

[joshanne]

@tridge @Huibean do either of you have any objections to using this approach?

[Huibean]

Hi @joshanne can you solve the version v0.0.0 issue when launching the tool directly from source? others looks OK to me

[joshanne]

@Huibean if possible, would you like to give it another look over? I've updated the above images to show the developer build working the same way.

it simplifies the release process atm, no manual editing of files... there is still one edge case, but its very unlikely to hit now. It allows developers to run the tool from their directory and get the current commit information at runtime.

If @tridge or the release maintainer is okay to slightly modify the release process, the release process then becomes...

• Tag the commit
• Build and Release the artifacts

In effect, the steps for loading the version here are then:

• attempt to extract the information from git describe
  • if present, use the git describe generated version
  • if not present, attempt to use the generated version file from setuptools_scm
    • If present, parse the autogenerated version info
    • If not present, fall back to git_archival.txt file, assuming downloaded from zip file on github
      • if that file isn't present... THEN we default to v0.0.0.

[Copilot]

Pull request overview

This PR improves how DroneCAN GUI Tool reports its version for development builds by adopting setuptools_scm-based version generation and surfacing additional metadata (e.g., post-release commit count / dirty state) in both CLI --version output and the About dialog.

Changes:

• Switch packaging to setuptools_scm and emit a generated version file at build time.
• Update the CLI --version output and About window to display dev/build metadata.
• Add Git archive substitution support via .gitattributes and a .git_archival.txt template for non-git source distributions.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
setup.py	Switches package versioning to setuptools_scm with write_to output.
pyproject.toml	Adds setuptools_scm[toml] to build-system requirements.
dronecan_gui_tool/widgets/about_window.py	Updates About dialog to show version + dev metadata.
dronecan_gui_tool/version.py	Adds runtime/build-time version resolution (git / generated file / archival).
dronecan_gui_tool/main.py	Updates --version output to include dev metadata and dirty warning.
.gitignore	Ignores the generated version file and venv directory.
.gitattributes	Enables export-subst for .git_archival.txt.
.git_archival.txt	Provides archive-substitution placeholders for version/commit metadata.

Suppressed comments (1)

dronecan_gui_tool/version.py:106

• Avoid printing to stdout/stderr at module import time. Importing dronecan_gui_tool.version during normal startup will emit this message and can interfere with --version output formatting or GUI launches. Prefer leaving the version as the default tuple (or logging/warnings at the call site where version is displayed).

            print("Warning: Git is not available and .git_archival.txt not found")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (4)

dronecan_gui_tool/main.py:54

• Dirty-build detection here only looks for the setuptools_scm-style ".dYYYYMMDD" marker, but version.py also appends the literal metadata part "dirty" for dirty source trees. As a result, --version may omit the dirty warning for source runs.

    metadata_parts = [x for x in __version_tuple__ if isinstance(x, str)]
    is_clean_release = len(metadata_parts) == 0
    is_dirty = any(".d" in part for part in metadata_parts)
    version_info = '.'.join(map(str, __version__))

dronecan_gui_tool/version.py:108

• This print() runs at import time when git metadata isn't available, which can pollute stdout/stderr for any consumer importing the package (including packaging/build tools). Prefer logging (or silence) over printing from a library module import path.

        else:
            print("Warning: Git is not available and .git_archival.txt not found")

dronecan_gui_tool/version.py:27

• version.py runs git describe unconditionally at import time. In installed wheels (no .git directory) this still spawns a git subprocess (and then falls back), adding avoidable startup overhead and an external tool dependency. Consider skipping the git call unless this is actually a git checkout.

This issue also appears on line 107 of the same file.

# 1. Try running git describe first (live git repository state)
try:

    git_describe = subprocess.check_output(
        ["git", "describe", "--tags", "--long", "--dirty"],
        stderr=subprocess.DEVNULL,
        text=True,
        cwd=os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    ).strip()

setup.py:50

• setuptools-scm is only needed to build the package/version metadata; it isn't imported or required at runtime. Keeping it in install_requires forces an unnecessary runtime dependency for end users.

    install_requires=[
        'setuptools>=18.5',
        'setuptools-scm>=6.2',
        'dronecan>=1.0.25',
        'pyserial>=3.0',

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (3)

dronecan_gui_tool/main.py:54

• Dirty working tree detection won't trigger with the parsed setuptools_scm metadata. version.py splits the version string into parts like d20260724, but this check looks for the substring .d, which won't be present in any individual part (so the warning is skipped even for dirty builds).

    metadata_parts = [x for x in __version_tuple__ if isinstance(x, str)]
    is_clean_release = len(metadata_parts) == 0
    is_dirty = any(".d" in part for part in metadata_parts)
    version_info = '.'.join(map(str, __version__))

dronecan_gui_tool/widgets/about_window.py:24

• The dirty build marker from setuptools_scm typically becomes a metadata part like dYYYYMMDD after splitting the version string. Checking for .d inside each part won't match, so the About dialog may omit the "Dirty" indicator even for dirty builds.

numeric_parts = [x for x in __version_tuple__ if isinstance(x, int)]
metadata_parts = [x for x in __version_tuple__ if isinstance(x, str)]
is_clean_release = len(metadata_parts) == 0
is_dirty = any((part == "dirty") or (".d" in part) for part in metadata_parts)
version_info = '.'.join(map(str, numeric_parts))

dronecan_gui_tool/version.py:36

• setuptools_scm's write_to file typically defines __version__ (a string), not __version_tuple__. Importing __version_tuple__ from _version_generated.py will fail for built artifacts, causing the version to fall back to the manual tuple (and emitting a warning), which defeats the purpose of use_scm_version.

    # 2. Try to import the generated version information (built wheels/MSIs)
    try:
        from ._version_generated import __version_tuple__  # noqa: F401
    except ImportError:

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (4)

dronecan_gui_tool/version.py:46

• setuptools_scm's write_to output defaults to a module containing __version__ (string). This code attempts to import __version_tuple__ from ._version_generated, so it will raise ImportError and always fall back to the manual version, defeating the purpose of writing the generated file.

        # 2. Try to import the generated version information (built wheels/MSIs)
        try:
            from ._version_generated import __version_tuple__  # noqa: F401
        except ImportError:
            # 3. Fall back to the manually updated version
            print("Warning: setuptools_scm is not available or failed with: ", e,
                  " and _version_generated.py not found. "
                  "Falling back to manual version.")

dronecan_gui_tool/version.py:50

• This module prints warnings to stdout during import (e.g., in shallow clones it intentionally raises an exception and then prints). That can corrupt --version output and other CLI output; prefer emitting warnings on stderr (or logging) and avoid warning for expected shallow-clone fallback.

    if os.path.exists(os.path.join(_root_dir, '.git', 'shallow')):
        raise Exception("Shallow clone detected, falling back to manual version")
    _version_str = get_version(root=_root_dir, version_scheme='post-release')
    # Parse the version string into a tuple
    _parts = []
    for _part in re.split(r'[-.+]', _version_str):
        if _part:
            try:
                _parts.append(int(_part))
            except ValueError:
                _parts.append(_part)
    __version_tuple__ = tuple(_parts)
except Exception as e:
    if not _is_source:
        # 2. Try to import the generated version information (built wheels/MSIs)
        try:
            from ._version_generated import __version_tuple__  # noqa: F401
        except ImportError:
            # 3. Fall back to the manually updated version
            print("Warning: setuptools_scm is not available or failed with: ", e,
                  " and _version_generated.py not found. "
                  "Falling back to manual version.")
    else:
        print("Warning: setuptools_scm is not available or failed with: ", e,
              " and running from source. "
              "Falling back to manual version.")

dronecan_gui_tool/main.py:54

• __version_tuple__ is produced by splitting the setuptools_scm version string on [-.+], so dirty builds become a part like "d20260724" (no leading dot). Checking for the substring ".d" will never match, so the dirty-working-tree warning won't be shown.

    metadata_parts = [x for x in __version_tuple__ if isinstance(x, str)]
    is_clean_release = len(metadata_parts) == 0
    is_dirty = any(".d" in part for part in metadata_parts)
    version_info = '.'.join(map(str, __version__))

dronecan_gui_tool/widgets/about_window.py:24

• __version_tuple__ comes from splitting the setuptools_scm version string on [-.+], so dirty builds are represented as a string part like "d20260724". The current check looks for ".d" (and the literal "dirty"), which won't match "dYYYYMMDD", so the About dialog can miss marking dev builds as dirty.

numeric_parts = [x for x in __version_tuple__ if isinstance(x, int)]
metadata_parts = [x for x in __version_tuple__ if isinstance(x, str)]
is_clean_release = len(metadata_parts) == 0
is_dirty = any((part == "dirty") or (".d" in part) for part in metadata_parts)
version_info = '.'.join(map(str, numeric_parts))