diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..8004983 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,7 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + open-pull-requests-limit: 5 diff --git a/CHANGELOG.md b/CHANGELOG.md index b50336b..2d7c342 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 2026-09-08 + + +### Added + +- Added private vulnerability-reporting guidance, project-specific contribution instructions, weekly GitHub Actions dependency updates, and public-repository hygiene guidance. + ## 2026-09-02 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bfe4d1e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,92 @@ +# Contributing to PiNative + +Thank you for helping improve PiNative. The project aims to be a polished native macOS GUI for Pi, with reliability and native Mac craft treated as equally important. + +## Before you start + +- Search existing issues and pull requests before opening a duplicate. +- Use an issue to discuss substantial features, architecture changes, or changes in product behavior before implementation. +- Keep each contribution focused. Do not combine unrelated cleanup with the requested change. +- Read [`AGENTS.md`](AGENTS.md) for repository-specific engineering guidance. + +## Development setup + +You need: + +- A Mac running macOS 14 or newer. +- The full Xcode app, selected with `xcode-select`. +- Pi installed and configured so `pi --mode rpc` starts successfully. + +Clone the repository and build it: + +```sh +git clone https://github.com/Unsupervisedcom/pi-native.git +cd pi-native +xcodebuild -project PiNative.xcodeproj -scheme PiNative \ + -configuration Debug -destination 'platform=macOS' build +``` + +You can also open `PiNative.xcodeproj`, select the `PiNative` scheme, and run with `⌘R`. See [`docs/build-and-run.md`](docs/build-and-run.md) for troubleshooting and release-build details. + +Optional local settings belong in ignored files: + +```sh +cp Config/Secrets.xcconfig.example Config/Secrets.xcconfig +cp Config/Signing.xcconfig.example Config/Signing.xcconfig +``` + +Only create these files when needed, and never commit credentials, tokens, signing identities, or local account details. + +## Requirements and testing + +Observable feature behavior is specified under [`specs/`](specs/) using RFC 2119 requirements. When changing product behavior, update or add the specification before adding requirement-linked tests. Follow the complete workflow in [`docs/requirements-and-testing.md`](docs/requirements-and-testing.md). + +Run the bounded unit and integration suite during development: + +```sh +scripts/test-unit.sh +``` + +Focused tests can be passed through to `xcodebuild`, for example: + +```sh +scripts/test-unit.sh -only-testing:PiNativeTests/ModelSettingsTests +``` + +Before submitting a change: + +1. Build the app and run the focused tests for the behavior you changed. +2. Run `npx --yes rfc2119 lint` when specifications change. +3. Run `npx --yes rfc2119 check` when requirement semantics or mapped test behavior changes. +4. Verify affected UI directly in the built app. UI automation controls the desktop, so run it only in an appropriate environment; use `scripts/test-ui-related.sh` for UI tests related to changed app files. +5. For behavior involving real Pi RPC events, authentication, provider state, session state, persistence, or process lifecycle, provide real-Pi integration evidence where safely repeatable. Do not present mock-only tests as end-to-end proof. + +## Pull requests + +A pull request should: + +- Explain the user-visible problem and the chosen solution. +- Link the relevant issue. +- Describe tests and direct verification performed, including any gaps. +- Include screenshots or recordings for intentional UI changes, while excluding private user data. +- Keep requirements, tests, and durable documentation aligned with behavior. +- Avoid generated build products, local configuration, unrelated formatting, and drive-by refactors. + +## Repository privacy and hygiene + +This is a public repository. Before committing, inspect both staged changes and newly added files. + +Do not commit: + +- Prompts, transcripts, provider responses, credentials, tokens, or private API data. +- Personal filesystem paths, project names, account details, or local session data. +- Private research, exploratory plans, or named third-party design references. Keep exploratory work under the ignored `research/` directory or outside the repository, and refer generically to a “reference app” in tracked material when needed. +- Ad hoc screenshots, recordings, test evidence, or generated reports. Store temporary evidence outside the repository, such as under `/tmp`. + +Intentional product assets and reviewed durable documentation may be tracked. In particular, `docs/readme-screenshot.png` is a public product asset, and `docs/code-architecture-walkthrough.html` is intentionally versioned as the browsable form of the Markdown-backed architecture walkthrough. When updating that walkthrough, follow [`docs/code-architecture-walkthrough.md`](docs/code-architecture-walkthrough.md), update its sources and rendered HTML together, and inspect the result before submitting it. + +Report security concerns privately as described in [`SECURITY.md`](SECURITY.md), never through a public issue. + +## License + +By contributing, you agree that your contribution is licensed under the repository's [MIT License](LICENSE). Bundled third-party assets retain their own licenses; review [`docs/THIRD_PARTY_LICENSES.md`](docs/THIRD_PARTY_LICENSES.md) before adding or replacing assets. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b817536 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,24 @@ +# Security Policy + +## Reporting a vulnerability + +Please do not report suspected vulnerabilities in a public issue, discussion, or pull request. + +Use GitHub's private vulnerability-reporting form instead: + + + +Include, when available: + +- A description of the vulnerability and its impact. +- The affected version, commit, or component. +- Reproduction steps or a proof of concept. +- Any suggested mitigation. + +Do not include real credentials, private prompts, user data, or other unnecessary sensitive material. Use minimal test data and clearly mark any details that require special handling. + +The maintainers will assess the report and coordinate disclosure and remediation through the private advisory. Please allow time for a fix before publishing details. + +## Supported versions + +PiNative is currently under active development without a packaged public release. Security fixes target the latest code on the default branch. diff --git a/docs/code-architecture-walkthrough.md b/docs/code-architecture-walkthrough.md index 30d46d5..9ba5fae 100644 --- a/docs/code-architecture-walkthrough.md +++ b/docs/code-architecture-walkthrough.md @@ -5,6 +5,8 @@ This is the maintenance entry point for the Markdown-backed architecture present - Rendered presentation: [`code-architecture-walkthrough.html`](code-architecture-walkthrough.html) - Slide sources: [`code-architecture-walkthrough/`](code-architecture-walkthrough/) +The rendered HTML is intentionally tracked as durable, browsable project documentation even though it is generated from the slide sources. Update and review the sources and HTML together; other generated reports remain temporary artifacts outside the repository. + The presentation is intentionally organized as a small set of high-level tabs rather than one long architecture document. Each slide should remain concise enough to walk through with a new developer while sharing a screen. ## Instructions for an agent refreshing the walkthrough