Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (65 loc) · 3.25 KB

CONTRIBUTING.md

File metadata and controls

88 lines (65 loc) · 3.25 KB
Raw

Contributing Guide

Thank you for improving Codex Quota. This repository currently provides source code only, and its development workflow relies on repeatable synthetic tests.

Good First Contributions

Useful starting points include:

  • improving English documentation and build instructions;
  • adding synthetic protocol or state fixtures for compatibility cases;
  • expanding accessibility and presentation tests;
  • making focused SwiftUI or AppKit interface refinements;
  • documenting reproducible behavior changes in newer Codex versions.

Before starting a larger change, open an Issue describing the scope and the synthetic verification you plan to add. Never attach real account data while asking for feedback.

Development Environment

  • Apple Silicon Mac
  • macOS 14 or later
  • Xcode command-line tools with Swift 6.2 support

Run these commands from the repository root:

swift test --parallel
swift build -c release --product CodexQuotaMonitor
Scripts/verify-settings-ax.sh --compile-only
Scripts/verify-version.sh

To inspect the local interface, then run:

Scripts/build-development-app.sh
open dist/development/CodexQuotaDev.app

The script creates an ad-hoc-signed development app with a separate development bundle, state directory, and Keychain service. It is not distributable and is not a release artifact. The script does not accept CODE_SIGN_IDENTITY.

Data Safety

Automated tests must not read a real CODEX_HOME, auth.json, state file, or Keychain and must not launch real Codex. New tests must use temporary directories, synthetic protocol frames, and obviously fictional account data.

Do not commit:

  • tokens, account IDs, real quota values, or notification history;
  • user names, host names, personal email addresses, or local absolute paths;
  • signing identities, certificates, provisioning profiles, or Keychain exports;
  • dist, .build, crash reports, or other generated artifacts.

Do not create a public Issue for a vulnerability. Follow the Security Policy and use GitHub Security Advisories.

Submit a Change

  1. Keep each change focused and avoid unrelated refactoring.
  2. Add or update tests for behavior changes.
  3. Run swift test --parallel.
  4. Update affected user and architecture documentation.
  5. Check the diff for real account or computer information.

A Pull Request must explain the problem, solution, verification commands, and remaining limitations. Do not present “passes on my Mac” as support for every Codex version.

Interface changes must update synthetic previews or explain why no preview applies. Do not use desktop recordings or real-account screenshots. User-visible behavior changes must update the README or relevant architecture documentation. Describe privacy-boundary changes separately in the Pull Request.

The current Package.swift declares no third-party package dependencies. If a change adds a dependency, image, font, or other third-party material, the Pull Request must identify its source, version, purpose, license, and redistribution terms and include required license text. Material with unclear provenance or licensing cannot be merged.

By contributing, you confirm that you have the right to submit the material and agree to publish it under the project's MIT License.