Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (43 loc) · 2.35 KB

CONTRIBUTING.md

File metadata and controls

59 lines (43 loc) · 2.35 KB
Raw

Contributing to Codex GoalPulse

Thanks for helping improve GoalPulse.

Before opening an issue

  • Search existing issues.
  • Run the latest main build when practical.
  • Include macOS version, Codex desktop version, GoalPulse version, and the exact command used.
  • Redact usernames, absolute home paths, goal titles, thread IDs, tokens, and account data.
  • Never upload a real ~/.codex/goals_*.sqlite database.

Development setup

Requirements:

  • macOS 13+
  • Xcode Command Line Tools
  • sqlite3 (included with macOS)
  • Python 3 for the Codex plugin hook and tests
make build
make test
make test-plugin
./scripts/verify.sh
make ci

make ci is the canonical pre-push entry point and is also called by the GitHub Actions macOS job. It verifies the app and plugin, runs the protocol and memory regressions, and builds both release archives. If act is installed, it also validates the workflow in strict dry-run mode. The project intentionally uses one small native Swift executable and shell-based packaging. Keep runtime dependencies at zero unless a change has a strong reason to add one.

Pull requests

  1. Create a focused branch.
  2. Keep unrelated formatting changes out of the patch.
  3. Add or update deterministic self-tests for behavior changes.
  4. Use synthetic fixtures for screenshots and database tests.
  5. Run make ci before opening the PR.
  6. Update CHANGELOG.md when the change affects users.

Compatibility changes

The status-only app-server protocol, Desktop IPC protocol, and goal database are integration boundaries. If any changes:

  • Document the observed Codex version.
  • Preserve the final thread/goal/get check before changing goal status.
  • Keep database access read-only.
  • Do not add UI automation as an implicit fallback.
  • Keep unattended approval handling fail-closed.

Style

  • Four spaces in Swift and two spaces in shell/YAML.
  • Prefer clear names and small, testable helpers.
  • README.md is the primary Chinese landing page; README.en.md is its English translation. Keep the README.<language>.md naming pattern and update both for feature changes.
  • Keep plugins/codex-goal-pulse/README.md and plugins/codex-goal-pulse/README.en.md aligned when plugin behavior changes.
  • Comments should explain why, not restate the code.

By contributing, you agree that your contribution is licensed under the repository’s MIT License.