Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
195 lines (129 loc) · 6.04 KB

CONTRIBUTING.md

File metadata and controls

195 lines (129 loc) · 6.04 KB

Contributing

Thanks for contributing to visionos-codex-kit.

This repository bundles three related deliverables:

  • installable Codex skills under skill/
  • reusable visionOS blueprints under blueprints/
  • maintenance and rebuild tooling under build-tools/

The main goal is to keep the repo useful for real Apple Vision Pro and visionOS development while keeping installation and bootstrap flows predictable.

Ground Rules

  • Keep main installable. A contributor should be able to clone the repo and run ./install.sh successfully.
  • Prefer small, focused changes over broad refactors.
  • Do not commit generated caches, temporary build outputs, or local test residue.
  • Treat skill/, blueprints/, and build-tools/ as distinct surfaces with different responsibilities.
  • When in doubt, optimize for reproducibility and low-maintenance repo structure.

Repository Map

  • skill/visionos-3d-development/: the main reference skill for RealityKit, ARKit, SwiftUI spatial APIs, immersive rendering, and related visionOS development guidance.
  • skill/visionos-app-bootstrap/: the bootstrap skill that teaches Codex how to scaffold new apps from the installed blueprint payload.
  • blueprints/templates/: ready-to-copy starter projects.
  • blueprints/shared-tools/: canonical helper scripts shared by the templates.
  • build-tools/: scripts, manifests, and small snapshots used to rebuild or refresh the skill content.
  • install.sh: the supported installation entry point.
  • VERSION: the coordinated repo version.

What To Edit

Edit the repo source, not installed copies under ~/.codex.

Typical contribution targets:

  • Skill content updates: edit files under skill/.
  • Blueprint improvements: edit files under blueprints/templates/ and, when appropriate, blueprints/shared-tools/.
  • Rebuild pipeline changes: edit files under build-tools/.
  • Installer behavior: edit install.sh and any related documentation.

If you change shared blueprint helpers in blueprints/shared-tools/, also sync them into the templates before submitting.

Development Setup

Clone the repo and work from the repository root:

git clone https://github.com/pardeike/visionos-codex-kit.git
cd visionos-codex-kit

Install the skills locally if you need to test the installed layout:

./install.sh

To inspect versioning without installing:

./install.sh --version
./install.sh --print-installed-version

Validation Expectations

Choose the checks that match the files you changed.

For skill content changes

  • Verify links, paths, and references are still valid.
  • Keep guidance latest-first and avoid stale platform assumptions.
  • Prefer official Apple sources for framework behavior and platform details.
  • Preserve clear structure so an LLM can navigate the skill quickly.

For blueprint changes

Run the relevant local helper scripts from the affected template.

Typical flow:

./tools/build_app_icon.sh
./tools/regenerate_project.sh

If the project behavior changed, also validate with Xcode build tooling such as xcodegen and xcodebuild, and use the included device deployment helper when appropriate:

./tools/deploy_to_active_device.sh

If you changed blueprints/shared-tools/, refresh the vendored copies inside the templates:

./blueprints/scripts/sync_shared_tools_into_templates.sh

For shell scripts

Use a syntax check:

bash -n path/to/script.sh

For Python scripts under build-tools/

Use:

python3 -m py_compile build-tools/scripts/*.py

For installer changes

At minimum, test:

./install.sh --version
./install.sh

If possible, also test with a temporary CODEX_HOME so the first-run path stays healthy.

Content Standards

Skills

  • Keep content practical and current.
  • Prefer precision over volume when the two conflict.
  • Do not duplicate large amounts of generated or derivative reference material without a clear retrieval benefit.
  • Keep file and folder structure intentional so Codex can load only the needed context.

Blueprints

  • Keep copied projects easy to rename and adapt.
  • Preserve the external icon workflow and active-device deployment workflow unless there is a strong reason to change them.
  • Avoid introducing hidden assumptions that only work on one machine.
  • Prefer self-contained template behavior over repo-relative runtime dependencies.

Build Tools

  • Commit manifests, scripts, and small reproducibility snapshots.
  • Do not commit heavy generated symbol graphs, caches, or temp directories.
  • Make rebuild steps deterministic where practical.

Commits And Pull Requests

Use clear, imperative commit messages, for example:

  • Fix mixed blueprint device signing sync
  • Refresh RealityKit source catalog
  • Document installer version metadata

For pull requests:

  • explain what changed
  • explain why it changed
  • list how you validated it
  • call out any known limitations or follow-up work

Screenshots are helpful for blueprint UX changes and GitHub-facing presentation updates.

Versioning

This repo uses one coordinated version for:

  • the skills
  • the installed blueprint payload
  • the installer contract

If your change affects published behavior, install layout, or release expectations, consider whether VERSION, release notes, or a follow-up tag will need updating.

Do not change the version casually as part of unrelated work.

Things To Avoid

  • editing installed copies in ~/.codex and treating them as source
  • committing large generated outputs
  • breaking ./install.sh
  • mixing unrelated blueprint, skill, and build-pipeline changes into one contribution without a good reason
  • silently changing release or install semantics

Questions And Issues

If you are unsure whether a change belongs in the skill, the blueprints, or the build pipeline, open an issue or describe the intended outcome before making a broad change.

Good issue reports include:

  • the affected area of the repo
  • the current behavior
  • the expected behavior
  • the validation environment, especially for visionOS, Xcode, and device-related problems