IGB-DOC-003¶

File Naming Convention¶

Document ID : IGB-DOC-003

Title : File Naming Convention

Version : v1.0

Status : Approved

Owner : IGB Engineering

Last Update : 2026-08

Revision History¶

Version	Date	Description
v1.0	2026-08	Initial Approved Release

1. Purpose¶

This document defines the official file naming convention for the IGB Engineering Platform.

The purpose of this standard is to establish a consistent, predictable, machine-readable, and maintainable naming system for engineering documentation, source files, configuration files, design artifacts, specifications, reports, releases, and related repository content.

This standard ensures that file names communicate document identity, function, and classification without relying on directory location alone.

2. Scope¶

This standard applies to all files maintained within the IGB Engineering Platform and its associated engineering repositories.

It applies to:

Engineering documentation
Architecture documents
Engineering specifications
Requirements
Hardware documentation
Software documentation
Firmware documentation
AI documentation
Validation records
Manufacturing documentation
Security documentation
Intellectual property documentation
Configuration records
Release documentation
Templates
Engineering reports
Supporting repository artifacts

This standard applies to both human-created and machine-generated engineering files where a controlled naming convention is required.

3. Authority¶

This document is a subordinate documentation standard under:

IGB-DOC-001 — Documentation Architecture

IGB-DOC-001 defines the overall documentation architecture and governing authority for the IGB Engineering Platform.

Where a conflict exists between this document and IGB-DOC-001, IGB-DOC-001 shall take precedence.

IGB-DOC-002 — Documentation Style Guide governs document presentation and formatting.

IGB-DOC-003 governs file naming.

Therefore:

IGB-DOC-001 defines documentation architecture.
IGB-DOC-002 defines documentation presentation.
IGB-DOC-003 defines file naming.
IGB-DOC-003 shall not override the authority of IGB-DOC-001.

4. Naming Principles¶

All controlled file names shall follow these principles:

File names shall be deterministic.
File names shall be machine-readable.
File names shall be human-readable.
File names shall identify the engineering artifact.
File names shall use stable identifiers where applicable.
File names shall avoid unnecessary version identifiers.
File names shall avoid spaces.
File names shall use consistent separators.
File names shall not contain ambiguous abbreviations where an approved identifier exists.
File names shall remain valid across supported filesystems and source-control systems.
File names shall not rely on directory location to establish document identity.
Controlled documents shall use their assigned document identifier.

5. General File Naming Format¶

The preferred controlled-document naming format is:

```text _.md Example: IGB-DOC-001_Documentation_Architecture.md IGB-DOC-002_Documentation_Style_Guide.md IGB-DOC-003_File_Naming_Convention.md The document version shall normally be maintained inside the document rather than embedded in the active filename.</p> <ol> <li> <p>Document Identifier Controlled documents shall use a unique document identifier. The identifier shall consist of: <ORGANIZATION>-<DOCUMENT-CLASS>-<NUMBER> Example: IGB-DOC-003 Where: IGB identifies the organization or engineering platform. DOC identifies the documentation class. 003 identifies the unique document number. Document identifiers shall remain stable throughout the controlled document lifecycle. A document identifier shall not be reused for a different document.</p> </li> <li> <p>Approved Document Prefixes The following document prefixes are defined by the documentation architecture: Prefix Description IGB-DOC Documentation IGB-ARCH Architecture Constitution IGB-ADR Architecture Decision Record IGB-ECN Engineering Change Notice IGB-ICD Interface Control Document IGB-EDF Engineering Design Freeze IGB-REQ Requirement IGB-SEC Security IGB-COM Communication IGB-VAL Validation IGB-MFG Manufacturing IGB-SW Software IGB-BOM Bill of Materials IGB-IP Intellectual Property IGB-REL Release</p> </li> </ol> <p>Additional prefixes shall not be introduced casually. New controlled prefixes shall be established through the applicable governance and documentation-control process.</p> <ol> <li> <p>Title Naming The title portion of a controlled filename shall: Use descriptive English terminology. Use words separated by underscores. Avoid unnecessary abbreviations. Match the document title where practical. Remain stable unless the document title is formally changed. Example: IGB-DOC-003_File_Naming_Convention.md Preferred: IGB-ARCH-000_Platform_Architecture.md Not preferred: IGB-ARCH-000_platform-final-new.md Not preferred: IGB-ARCH-000_Platform Architecture.md</p> </li> <li> <p>Separators The following separator rules shall apply. 9.1 Identifier Separator Hyphens shall be used inside structured identifiers. Example: IGB-DOC-003 9.2 Filename Word Separator Underscores shall be used between filename words. Example: File_Naming_Convention 9.3 Directory Separator The filesystem directory separator shall remain: / Example: docs/standards/IGB-DOC-003_File_Naming_Convention.md</p> </li> <li> <p>Spaces Controlled filenames shall not contain spaces. Incorrect: IGB-DOC-003 File Naming Convention.md Correct: IGB-DOC-003_File_Naming_Convention.md Spaces may exist inside document content, titles, or human-readable descriptions.</p> </li> <li> <p>Version Naming Active controlled documents shall not normally include the document version in the filename. Correct: IGB-DOC-003_File_Naming_Convention.md Incorrect: IGB-DOC-003_File_Naming_Convention_v1.0.md The version shall be recorded in the document metadata and revision history. Example: Version : v1.0 Historical or archived documents may retain their historical filename when required to preserve repository history or archival identity.</p> </li> <li> <p>Status Naming Document status shall not normally be encoded into the active filename. Do not use: IGB-DOC-003_File_Naming_Convention_APPROVED.md or: IGB-DOC-003_File_Naming_Convention_FINAL.md Status shall be maintained inside the document metadata. Example: Status : Approved</p> </li> <li> <p>Draft Files Temporary or working drafts shall not be mistaken for controlled active documents. Where a draft must be stored in the repository, its status shall be explicit through repository organization or an approved draft convention. A draft shall not silently replace an Approved or Active controlled document.</p> </li> <li> <p>Backup Files Backup files shall not be stored in active controlled-document locations unless explicitly required by repository procedures. The following filename patterns shall not be used for active controlled documents: <em>.bak </em>.backup <em>.old </em>.tmp Historical backups shall be stored under the applicable archive or backup mechanism. Git is the authoritative source for controlled-document history.</p> </li> <li> <p>Archive Files Superseded documents shall be moved to: docs/archive/ Archived filenames may preserve historical naming when required for traceability. Example: docs/archive/IGB-DOC-003_File_Naming_Convention_v1.0.md Archive files are historical records and shall not be treated as the current active document.</p> </li> <li> <p>File Extensions The file extension shall identify the actual file format. Common controlled engineering documentation formats include: .md .pdf .docx .xlsx .csv .yaml .yml .json .py .sh The extension shall not be used to misrepresent the actual file type. Example: IGB-DOC-003_File_Naming_Convention.md</p> </li> <li> <p>Markdown Files Controlled Markdown documentation shall use: <DOCUMENT-ID>_<TITLE>.md Example: IGB-DOC-003_File_Naming_Convention.md Markdown filenames shall use lowercase extensions: .md</p> </li> <li> <p>Configuration Files Configuration files shall use names that clearly identify their function. Examples: mkdocs.yml rules.yaml config.yaml Configuration filenames shall not unnecessarily include revision identifiers.</p> </li> <li> <p>Source Code Files Source code filenames shall describe their implementation role. Examples: classifier.py cache.py rule_engine.py repository_scanner.py Source files shall follow the naming convention appropriate to their programming language while remaining consistent with the repository's established conventions.</p> </li> <li> <p>Test Files Test files shall clearly identify the implementation unit being tested. Preferred examples: test_classifier.py test_cache.py test_rule_engine.py Test naming shall remain deterministic and directly associated with the tested implementation.</p> </li> <li> <p>Shell Scripts Operational shell scripts shall use descriptive names. Examples: start_all_services.sh stop_all_services.sh repository_cleanup.sh Scripts shall not use ambiguous names such as: run.sh new.sh test2.sh final.sh unless their meaning is explicitly defined by the repository structure.</p> </li> <li> <p>Directory Naming Directories are part of the repository naming system. Controlled documentation directories shall follow the architecture defined by IGB-DOC-001. Examples: docs/architecture/ docs/engineering/ docs/requirements/ docs/security/ docs/validation/ docs/manufacturing/ docs/software/ docs/specifications/ docs/standards/ docs/templates/ docs/archive/ Directory names shall be: lowercase where the documentation architecture defines lowercase names; descriptive; stable; free of unnecessary spaces; consistent with IGB-DOC-001.</p> </li> <li> <p>Canonical Active Document Location The active IGB documentation standards shall be stored under: docs/standards/ Examples: docs/standards/IGB-DOC-001_Documentation_Architecture.md docs/standards/IGB-DOC-002_Documentation_Style_Guide.md docs/standards/IGB-DOC-003_File_Naming_Convention.md The active repository location shall be treated as the canonical location for the corresponding controlled document.</p> </li> <li> <p>Duplicate Documents A controlled document identifier shall correspond to one active canonical document. Duplicate active documents using the same document identifier are prohibited. For example, the following shall not simultaneously exist as active documents: docs/IGB-DOC-003_File_Naming_Convention.md docs/standards/IGB-DOC-003_File_Naming_Convention.md If a duplicate is discovered, one file shall be designated as canonical and the other shall be removed, archived, or otherwise dispositioned through the applicable repository-control process.</p> </li> <li> <p>References References to controlled documents shall use the document identifier and canonical title. Preferred: IGB-DOC-003 — File Naming Convention Where a repository path is required, use the canonical active path: docs/standards/IGB-DOC-003_File_Naming_Convention.md References shall not point to superseded active locations.</p> </li> <li> <p>Traceability A controlled filename shall provide sufficient information to identify the associated engineering artifact. At minimum, a controlled document shall be traceable through: Document ID Title Repository Location Version Status Revision History The filename itself shall not be the sole source of document metadata.</p> </li> <li> <p>Machine Readability Filenames shall support automated repository processing. The naming convention shall allow tools to: identify document classes; identify document numbers; identify controlled documents; locate canonical documents; distinguish active and archived records; perform repository classification; validate naming compliance; generate indexes; construct documentation inventories. Filename structures shall therefore remain deterministic.</p> </li> <li> <p>Naming Validation Repositories implementing automated documentation governance should validate: Document identifier format. Duplicate document identifiers. Duplicate active documents. Invalid filename separators. Spaces in controlled filenames. Embedded active version numbers. Invalid extensions. References to superseded paths. Archive placement. Canonical-path compliance. Naming validation may be integrated with repository-management and engineering-governance tooling.</p> </li> <li> <p>Compliance All controlled documentation shall comply with this standard. A file that violates this naming convention shall be considered non-compliant until corrected or formally dispositioned. Exceptions shall require an explicit engineering or governance decision and shall be traceable.</p> </li> <li> <p>Relationship to Other Standards This document shall be interpreted together with: Document Relationship IGB-DOC-001 Parent documentation architecture and authority IGB-DOC-002 Documentation presentation and style IGB-DOC-003 File naming authority IGB-DOC-004 Engineering drawing standard IGB-DOC-005 Version control policy IGB-DOC-006 Git workflow standard</p> </li> </ol> <p>IGB-DOC-003 governs filename structure and shall not supersede higher-level governance requirements.</p> <ol> <li> <p>Authority Relationship The documentation standards relationship is: IGB-DOC-001 Documentation Architecture │ ├── IGB-DOC-002 │ Documentation Style Guide │ ├── IGB-DOC-003 │ File Naming Convention │ ├── IGB-DOC-004 │ Engineering Drawing Standard │ ├── IGB-DOC-005 │ Version Control Policy │ └── IGB-DOC-006 Git Workflow Standard IGB-DOC-001 remains the parent documentation authority. IGB-DOC-003 is the authoritative standard for file naming within its defined scope.</p> </li> <li> <p>Approval This document is released as: IGB-DOC-003 File Naming Convention Version : v1.0 Status : Approved The approved release establishes the baseline file naming convention for the IGB Engineering Platform.</p> </li> </ol> <p>Appendix A — Naming Examples Correct IGB-DOC-001_Documentation_Architecture.md IGB-DOC-002_Documentation_Style_Guide.md IGB-DOC-003_File_Naming_Convention.md IGB-ARCH-000_Platform_Architecture.md IGB-REQ-001_System_Requirements.md IGB-SEC-001_Security_Architecture.md Incorrect IGB-DOC-003 File Naming Convention.md IGB-DOC-003_File Naming Convention.md IGB-DOC-003_File_Naming_Convention_v1.0.md IGB-DOC-003_File_Naming_Convention_FINAL.md IGB-DOC-003-new.md</p> <p>Appendix B — Canonical Pattern Controlled documentation: <DOCUMENT-ID>_<TITLE>.<EXTENSION> Example: IGB-DOC-003_File_Naming_Convention.md</p> <p>Appendix C — Canonical Repository Structure docs/ ├── architecture/ ├── engineering/ ├── requirements/ ├── communication/ ├── security/ ├── validation/ ├── manufacturing/ ├── software/ ├── bom/ ├── releases/ ├── intellectual-property/ ├── products/ ├── specifications/ ├── patents/ ├── standards/ ├── templates/ └── archive/</p> <p>Appendix D — Canonical Path docs/standards/IGB-DOC-003_File_Naming_Convention.md This path is the canonical active repository location for IGB-DOC-003.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> </main> <footer class="md-footer"> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script> <script src="../../assets/javascripts/bundle.d7400e89.min.js"></script> <script> var livereload = function(epoch, requestId) { var req, timeout; var poll = function() { req = new XMLHttpRequest(); req.onloadend = function() { if (parseFloat(this.responseText) > epoch) { location.reload(); } else { timeout = setTimeout(poll, this.status === 200 ? 0 : 3000); } }; req.open("GET", "/livereload/" + epoch + "/" + requestId); req.send(); } var stop = function() { if (req) { req.abort(); } if (timeout) { clearTimeout(timeout); } req = timeout = undefined; }; window.addEventListener("load", function() { if (document.visibilityState === "visible") { poll(); } }); window.addEventListener("visibilitychange", function() { if (document.visibilityState === "visible") { poll(); } else { stop(); } }); window.addEventListener("beforeunload", stop); console.log('Enabled live reload'); } livereload(60776, 12480257); </script></body> </html>