Repository navigation
State the Fleet Standard for Script and Utility File Names #3140
Description
Problem
No fleet rule says how a script or utility file is named. CODESTYLE.md has no file-naming section, and GOVERNANCE.md "Repo-Scoped Secrets" shows snake_case example names without ever stating a casing. As a result, repositories mix conventions: hyphenated Python modules, PascalCase shell scripts, and secret files with hyphenated and snake_case stems side by side. The audit has nothing to check them against.
Agreed standard
| Type | Rule | Basis |
|---|---|---|
Python .py |
lowercase snake_case | PEP 8 module naming. A hyphenated module also cannot be imported |
Shell .sh and PowerShell .ps1 |
lowercase-hyphenated | The Linux CLI convention. A cross-platform pair keeps one name, sync-tools.sh beside sync-tools.ps1 |
Windows batch .cmd and .bat |
lowercase-hyphenated | The same convention as shell and PowerShell. A shim that puts a command on PATH takes the name of the command it provides, sync-tools.cmd launching sync-tools.ps1 |
PowerShell functions inside a .ps1 |
Verb-Noun with an approved verb (Get-Verb) |
PSScriptAnalyzer PSUseApprovedVerbs. This is a command rule, not a file rule |
| Env and secret files | lowercase snake_case stem | mail_relay.env, db_root_password |
| Env variable names and CI secret names | UPPER_SNAKE_CASE | POSIX and GitHub convention |
Clauses:
- Installed commands. An extensionless executable placed on
PATHor into a system slot (systemd, cron, run-parts, motd) is named as a command: lowercase-hyphenated with no extension, whatever language it is written in. - Wrapper exemption. A thin launcher whose only job is to run a Python tool keeps that tool's stem, so
fetch_report.py,fetch_report.sh, andfetch_report.ps1stay grouped together. - Externally fixed names are exempt. Git hook names,
__init__.py,conftest.py, Pester's.Tests.ps1suffix (its stem mirrors the script under test), a PowerShell data file (.psd1) whose name a tool fixes, such as a module manifest named for its module orPSScriptAnalyzerSettings.psd1, which PSScriptAnalyzer finds by that name, and any name a platform defines. - Directories are out of scope.
Departures, stated on purpose so a reader does not "fix" them back:
- The Google Shell Style Guide asks for underscores in shell file names. The fleet uses hyphens instead, matching installed Linux commands and the existing scripts.
- Microsoft's approved verbs govern command names. A
.ps1run by path is a file rather than an exported command, so the file takes the shell convention and its functions take Verb-Noun.
Python follows PEP 8.
Work
- Add a General subsection "Script and Utility File Names" to
CODESTYLE.mdstating the table, the clauses, and the departures. - Add one bullet to
GOVERNANCE.md"Repo-Scoped Secrets" stating that a secret file's stem is lowercase snake_case. - Sweep every surface that already states part of this, such as the
python-codestyleSkill's module-naming line, so the rule has one home and the others point to it.
Both files are carried, so the rule reaches every fleet repository on its next resync. Follow-up audit checks and renames are filed separately and depend on this issue.
Activity
ptr727 commentedon Oct 16, 2026
Waiting on this issue: ptr727/HomeAutomation-Config#1117 (script renames) and ptr727/HomeAutomation-Config#1118 (secret file stems with a host migration). Hub follow-ups: #3141, #3142, #3143.
State the Fleet Standard for Script and Utility File Names (#3198)
Promote the Script File-Naming Standard and the Suppressed Unread Che…
Rename the Carried hub-fetch-run.py Snippet to hub_fetch_run.py (#3219)