Skip to content
This repository was archived by the owner on Sep 22, 2026. It is now read-only.

conventions.md

Latest commit

 

History

History
131 lines (101 loc) · 4.98 KB

conventions.md

File metadata and controls

131 lines (101 loc) · 4.98 KB
Raw
authority canonical
applies-to intune-my-macs/
last-reviewed 2026-06-25
owners
alias role
theneiljohnson
docs
alias role
CKunze-MSFT
docs
review-cadence quarterly
audience agent

Conventions

Day-to-day code, content, and structure conventions for intune-my-macs. These complement the formal standards in ../standards/policy-naming-standard.prd and ../standards/manifest-standard.prd, and the agent entry point at ../AGENTS.md.

Repository layout

Platform artifact content lives under a per-platform folder (today: macOS/). The deployment engine (mainScript.ps1), the GUI (Start-IntuneMyMacs.ps1), developer tooling (tools/), and the standards (standards/) live at the repository root. mainScript.ps1 selects a platform with --platform (default macOS).

Artifacts and manifests

  • Every deployable artifact (.json Settings Catalog policy, .mobileconfig custom configuration, device script, or .pkg) has a sibling .xml manifest with a <MacIntuneManifest> root.
  • mainScript.ps1 discovers artifacts by scanning the selected platform folder (e.g. macOS/) for these manifests. A file with no manifest is never deployed — this is how helper files (including scripts/verify.ps1 and the tooling in tools/) stay out of tenant deployments.
  • Each manifest must declare:
    • a unique <ReferenceId> in TYPE-CATEGORY-NUMBER format (e.g. POL-SEC-001, CFG-SEC-001, SCR-APP-100, CAT-SYS-100, APP-UTL-001);
    • a <SourceFile> that resolves to a real file in the repo;
    • a plausible <SettingsCount>.

Reference IDs

  • TYPE (3 letters): POL policy, CMP compliance, CFG custom config (mobileconfig), SCR shell script, CAT custom attribute, APP app package.
  • CATEGORY (2–3 letters): SEC, MDE, IDP, CMP, SYS, APP, UTL.
  • NUMBER: zero-padded 3 digits. 001–099 reserved for core/critical items; 100–999 assigned sequentially. Numbers are never reused.

Filenames mirror the reference ID in lowercase with a short slug, e.g. macOS/configurations/intune/pol-sec-001-filevault.json, macOS/scripts/intune/scr-app-100-install-company-portal.sh.

Display names

[Prefix] [Reference] - [Descriptive Name], e.g. [intune-my-macs] POL-SEC-001 - FileVault Disk Encryption. Use Title Case, front-load keywords, separate reference and description with -, no trailing punctuation.

Settings Catalog JSON

  • settings[] entries must use contiguous, 0-based string IDs: "0", "1", "2", … Gaps or non-zero starts break import.
  • JSON must be well-formed (validated by scripts/verify.ps1). Intune/Graph exports may carry a UTF-8 BOM; that is tolerated.

Scripts

  • Shell scripts target macOS and run via Intune as the listed user (usually system). Keep a clear shebang (#!/bin/zsh or #!/bin/bash).
  • Log under /Library/Logs/Microsoft/IntuneScripts/... following the existing scripts' pattern.
  • PowerShell targets PowerShell 7+.

Copyright headers

Every first-party source file must carry the Microsoft header immediately after the shebang (or at the top for files without one):

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

Use the comment style for the language (# for shell/PowerShell/Python/YAML, <!-- --> for Markdown/XML). Never remove a pre-existing third-party copyright notice — for third-party scripts (e.g. community installers), keep the original author's attribution and do not stamp a Microsoft copyright over it. See the OSPO guidance: https://github.com/opensource-microsoft/docs/blob/main/docs/releasing/general-guidance/copyright-headers.md.

Generated documentation

INTUNE-MY-MACS-DOCUMENTATION.md is generated by python3 tools/Generate-ConfigurationDocumentation.py. Never hand-edit it. Regenerate it whenever artifacts change and commit the result.

Changelog and commits

  • Add one row per logical change to the top of the CHANGELOG.md table (newest first), linking every file path mentioned.
  • Commit in small, logical units (one concern per commit). Never use --no-verify; never force-push or git reset --hard published commits.

Ownership & maintenance

  • Review ownership is defined in ../.github/CODEOWNERS; the repo keeps two direct owners per the OSPO durable-owner standard.
  • Agent-context files (AGENTS.md, docs/, standards/, the Copilot instructions) are reviewed whenever the artifacts or workflow they describe change; the release checklist (../.github/prompts/ship.prompt.md) is the cadence that keeps them current.

Validate before pushing

Run the local loop:

pwsh ./scripts/verify.ps1

The full release flow is documented in ../.github/prompts/ship.prompt.md.