Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
45 lines (29 loc) · 2.83 KB

CONTRIBUTING.md

File metadata and controls

45 lines (29 loc) · 2.83 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, Ruby 4, and just. Install the lint and analysis tools required by just check with Homebrew:

brew install ruby just lychee swiftlint typos-cli zizmor
export PATH="$(brew --prefix ruby)/bin:$PATH"
bundle install
just install-hooks
just site-install
just check

just check performs a clean npm install, dependency-policy 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.

Dependabot alerts and security updates handle newly disclosed dependency vulnerabilities independently of CI and deployment. Run npm --prefix site run audit for a manual audit; findings do not gate unrelated changes or deployments.

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.