Pre-commit hook enforcing current copyright year on new files (#832)

## Summary
Enforce correct copyright start year on new files via pre-commit hook
and update the Agents.md, a reccuring mistake caught in PR reviews (for
example new files carry `2025-2026` isntead of just `2026`).

## Detailed description
Our pre-commit hooh `insert-license --use-current-year` only guarantees
the *current* year is present, so it passes a pasted range like
`2025-2026` on a brand-new 2026 file.

Adds `tools/fix_new_file_copyright_year.py` hook that rewrites the
copyright *start* year of newly added Python (and yaml) files to the
current year.

---------

Signed-off-by: Clemens Volk <cvolk@nvidia.com>

Author: cvolkcvolk

.pre-commit-config.yaml

@@ -75,3 +75,9 @@ repos:
         language: system
         pass_filenames: false
         types: [python]
+      - id: fix-new-file-copyright-year
+        name: Rewrite new files to use the current copyright year
+        entry: python3 tools/fix_new_file_copyright_year.py
+        language: system
+        types_or: [python, yaml]  # match insert-license's .(py|ya?ml)$ scope
+        exclude: "submodules/"

AGENTS.md

@@ -47,6 +47,7 @@ Lint and format tooling (`pre-commit` and the hooks it runs — black, flake8, i
 - Prefer `assert condition, "message"` over `if not condition: raise ValueError("message")` for internal invariant checks. (Formatting, imports, and typing are enforced by `pre-commit` — see `.pre-commit-config.yaml`.)
 - PR bodies follow `.github/pull_request_template.md` — a one-line Summary plus 2–5 detail bullets. Resist the agent default of long, multi-section descriptions.
 - Attribute docstrings should be included below the attribute, rather than in the class-level docstring.
+- Copyright headers: a newly created file uses the current year alone (e.g. `2026`); a file created earlier and edited this year uses a range (e.g. `2025-2026`). Don't copy a neighbouring file's year — the pre-commit hooks (`insert-license`, `fix-new-file-copyright-year`) set and enforce this, so you generally don't hand-edit it.
 
 ## Docstrings style
 

isaaclab_arena/tests/test_fix_new_file_copyright_year.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the tools/fix_new_file_copyright_year.py pre-commit hook."""
+
+from __future__ import annotations
+
+import importlib.util
+from datetime import date
+from pathlib import Path
+
+CURRENT_YEAR = str(date.today().year)
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_SCRIPT = _REPO_ROOT / "tools" / "fix_new_file_copyright_year.py"
+_LICENSE_TEMPLATE = _REPO_ROOT / ".github" / "LICENSE_HEADER.txt"
+
+
+def _load_hook():
+    """Import tools/fix_new_file_copyright_year.py (a standalone script, not an installed module)."""
+    spec = importlib.util.spec_from_file_location("fix_new_file_copyright_year", _SCRIPT)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+hook = _load_hook()
+
+
+def _header(years: str) -> str:
+    """Return a minimal Python source string with an Arena copyright header for the given year(s)."""
+    return (
+        f"# Copyright (c) {years}, The Isaac Lab Arena Project Developers "
+        "(https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).\n"
+        "# All rights reserved.\n#\n# SPDX-License-Identifier: Apache-2.0\n\nx = 1\n"
+    )
+
+
+def test_header_years_parses_single_and_range() -> None:
+    assert hook.header_years(_header(CURRENT_YEAR)) == CURRENT_YEAR
+    assert hook.header_years(_header("2020-2025")) == "2020-2025"
+    assert hook.header_years("x = 1\n") is None
+
+
+def test_regex_matches_the_real_license_template() -> None:
+    # The other tests build the header by hand; this guards against ARENA_RE drifting away from the
+    # canonical .github/LICENSE_HEADER.txt that insert-license actually writes (e.g. an org rename).
+    assert hook.header_years(_LICENSE_TEMPLATE.read_text(encoding="utf-8")) is not None
+
+
+def test_new_file_with_pasted_range_is_rewritten() -> None:
+    fixed = hook.fix_header_year(_header(f"2020-{CURRENT_YEAR}"), CURRENT_YEAR, is_new=True)
+    assert fixed == _header(CURRENT_YEAR)
+
+
+def test_new_file_with_current_year_needs_no_change() -> None:
+    assert hook.fix_header_year(_header(CURRENT_YEAR), CURRENT_YEAR, is_new=True) is None
+
+
+def test_existing_file_is_left_alone() -> None:
+    # A file already in HEAD keeps its start year even when it differs from the current year;
+    # the end year is the insert-license hook's responsibility, not this one's.
+    assert hook.fix_header_year(_header(f"2020-{CURRENT_YEAR}"), CURRENT_YEAR, is_new=False) is None
+
+
+def test_file_without_arena_header_is_ignored() -> None:
+    assert hook.fix_header_year("x = 1\n", CURRENT_YEAR, is_new=True) is None
+
+
+def test_yaml_header_is_also_rewritten() -> None:
+    # The header format and git detection are language-agnostic: YAML files carry the same
+    # "# Copyright (c) ..." header, so widening the hook to YAML needs no logic change.
+    yaml = (
+        f"# Copyright (c) 2020-{CURRENT_YEAR}, The Isaac Lab Arena Project Developers "
+        "(https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).\n"
+        "# All rights reserved.\n#\n# SPDX-License-Identifier: Apache-2.0\n\nkey: value\n"
+    )
+    fixed = hook.fix_header_year(yaml, CURRENT_YEAR, is_new=True)
+    assert fixed is not None
+    assert fixed.startswith(f"# Copyright (c) {CURRENT_YEAR},")
+
+
+def test_added_paths_keeps_adds_and_drops_renames_and_edits() -> None:
+    # Lines from `git diff --cached --name-status`: A=added, R<score>=renamed, M=modified.
+    # Only true additions are "new"; a rename (the bug this guards against) keeps its start year.
+    status = "A\tfresh.py\nA\tconfig.yaml\nR100\told.py\tnew.py\nM\tseed.py\n"
+    assert hook.added_paths(status) == {"fresh.py", "config.yaml"}

tools/fix_new_file_copyright_year.py

@@ -0,0 +1,82 @@
+# Copyright (c) 2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Auto-fix the start year of the Arena copyright header on newly added Python and YAML files.
+
+A file added in the current commit must carry the current year alone (e.g. ``2026``);
+a pasted range such as ``2025-2026`` is rewritten to ``2026``. Existing files and the
+end year are left to the ``insert-license`` hook.
+"""
+
+import re
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+# Captures the year string of the Arena copyright line, splitting off the literal
+# prefix/suffix so a rewrite only touches the year(s).
+ARENA_RE = re.compile(r"(Copyright \(c\) )(\d{4}(?:-\d{4})?)(, The Isaac Lab Arena Project Developers)")
+
+
+def header_years(text: str) -> str | None:
+    """Return the Arena copyright header's year string (e.g. '2025' or '2025-2026'), or None if absent."""
+    m = ARENA_RE.search(text)
+    return m.group(2) if m else None
+
+
+def fix_header_year(text: str, current_year: str, is_new: bool) -> str | None:
+    """Return text with the Arena copyright start year set to current_year, or None if no change is needed.
+
+    Only newly added files are rewritten; an existing file's start year is preserved (its end year is
+    the insert-license hook's responsibility). A missing header or an already-correct year yields None.
+    """
+    years = header_years(text)
+    if years is None or not is_new or years == current_year:
+        return None
+    return ARENA_RE.sub(rf"\g<1>{current_year}\g<3>", text, count=1)
+
+
+def added_paths(status_output: str) -> set[str]:
+    """Return the paths added from scratch, parsed from ``git diff --cached --name-status`` output.
+
+    Each line is ``<status>\\t<path>`` (``R<score>\\t<old>\\t<new>`` for a rename). Only status ``A``
+    counts as new; a rename is reported as ``R`` and excluded, so a moved file keeps its original
+    start year instead of having it reset to the current year.
+    """
+    return {line.split("\t")[1] for line in status_output.splitlines() if line.startswith("A\t")}
+
+
+def staged_status() -> str:
+    """Return ``git diff --cached --name-status`` for the staged changes, with renames detected."""
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--find-renames", "--name-status"],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout
+
+
+def main(argv: list[str]) -> int:
+    current = str(date.today().year)
+    new_files = added_paths(staged_status())
+    exit_code = 0
+    for path in argv:
+        file = Path(path)
+        try:
+            text = file.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        new_text = fix_header_year(text, current, is_new=path in new_files)
+        if new_text is None:
+            continue
+        file.write_text(new_text, encoding="utf-8")
+        print(f"{path}: new file copyright year '{header_years(text)}' rewritten to '{current}'")
+        exit_code = 1
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))