Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
41 lines (26 loc) · 2.57 KB

CONTRIBUTING.md

File metadata and controls

41 lines (26 loc) · 2.57 KB
Raw

Contributing to macOSdb

Thank you for improving macOSdb. Changes may affect a native scanner, a public data set, a CLI, a website, and automated release infrastructure, so please preserve the boundaries described below.

Development setup

Development requires Apple silicon, macOS 15 or newer, Swift 6.2, Node.js 26, Python 3, and just. Install the optional lint tools used by just check with Homebrew:

brew install actionlint just lychee periphery swiftlint typos-cli zizmor
just install-hooks
just site-install
just check

just check performs a clean npm install, dependency-policy and vulnerability checks, Swift and script tests, static analysis, site formatting and type checks, a production build, a Cloudflare deployment dry-run, and link checking. Individual recipes are documented in the README.

Source changes

  • Treat IPSW, XIP, IM4P, dyld cache, plist, archive, and JSON input as untrusted. Preserve bounds checks, timeouts, path confinement, and identity checks.
  • Add focused regression tests for parser boundaries and failure paths. A fixture should be the smallest input that proves the behavior.
  • Keep macOSdbCore independent of CLI presentation. The executable target owns argument parsing and terminal output.
  • Update the website, linter, tests, and data schema together when a public field or tracked-component contract changes.

Release data

Do not hand-edit files under data/. Release files and indexes are generated by the dispatch-only scanner workflows and are licensed under CC-BY-4.0. Scanner changes that add or remove a required component need a coordinated corpus migration; CI intentionally rejects partial component sets.

For local experiments, write to a temporary output directory. Never commit IPSW or XIP archives, checksum sidecars, AEA keys, signing material, or local environment files.

Commits and pull requests

Use Conventional Commits and certify every commit under the Developer Certificate of Origin:

git commit -s -m "fix(scanner): reject oversized metadata"

Do not commit directly to main. Keep a pull request focused, explain the behavior change and its operational consequences, and state how it was verified. When an AI or LLM assisted with the pull request, the final unformatted line of the initial description must be AI disclosure: <model> with <how the output was verified>.

Report suspected vulnerabilities privately as described in SECURITY.md.