diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..cc44e7e --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,40 @@ +# Contributing + +## Open an issue first +Every PR needs an issue. Search the existing issues before opening a new one: +- If it's already been reported, use that issue. +- If that issue is closed, comment there saying why it should be reopened. + +## Pull requests +- Link the issue with `Closes #N`, and keep the PR to what it asks for. +- Say how you tested it: the tests you added or ran, and a screen recording for UI changes. +- Say what you couldn't test. Screen Time, NFC and real location don't work in the simulator. +- CI must pass. + +Build, test and project-file notes are in [AGENTS.md](../AGENTS.md). + +## AI tools +AI tools are accepted, but review everything they produce yourself before opening a PR. +You're responsible for the result. +- Say in the PR description which tools you used and for what. If an agent wrote code, + add a `Co-authored-by: ()` line there. +- Commits are authored by your own account only. Don't add an AI as author or co-author + of a commit, including `Co-authored-by` trailers. +- Understand every change and be able to explain it. Reply to review comments yourself. +- Don't weaken or delete tests to make them pass. +- If tests need changing, provide justification. +- PRs that look unreviewed may be closed without review. + +## Hard to reverse +Changes here can break installed apps, widgets or people's Shortcuts. Agree on them in +the issue first: +- SwiftData models, which need a migration +- Data shared through the App Group between the app and its extensions +- `normal://` links and widget intent and entity types +- Keychain items +- App Intents and Shortcuts names and parameters +- Screen Time store and activity names +- Entitlements and permission prompts + +## Security +Report vulnerabilities privately, as described in [SECURITY.md](SECURITY.md). diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..e5b4292 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,22 @@ +# Security + +Report vulnerabilities privately through +[private vulnerability reporting](https://github.com/normalengineering/normal/security/advisories/new), +not in a public issue. + +Include the iOS version, device, and steps to reproduce or a screen recording. +Unverified AI-generated reports will be closed. + +Only the latest App Store version is supported. + +## In scope +- Unblocking apps, groups or websites without a valid key +- Getting past a block, schedule or daily limit from inside Normal +- Weaknesses in how NFC, QR code / barcode or location keys are checked +- Data leaving the device + +## Out of scope +- Bypasses through iOS Settings or Screen Time covered in Normal's FAQ +- iOS and Screen Time bugs, which go to Apple +- Copies of a key you've shared, such as a photo of a QR code or a cloned NFC tag +- Jailbroken devices diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..fbc3fd0 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,12 @@ +Closes # + +## What and why + +## How it was tested + + +## AI use + + +- [ ] Touches a "Hard to reverse" area in CONTRIBUTING.md, agreed in the issue diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..930b134 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# AGENTS.md + +Normal is an iOS Screen Time blocker in SwiftUI and SwiftData, using FamilyControls, +ManagedSettings and DeviceActivity. It has no third-party dependencies. + +## Targets +- `Normal`: the app +- `NormalMonitor`: DeviceActivity extension (schedules, timed unblock expiry) +- `NormalShield`: shield screen +- `NormalWidget`: widgets, Live Activity, controls +- `Shared/`: code used by the app and the extensions + +## Build and test +```sh +xcodebuild test -project Normal.xcodeproj -scheme Normal \ + -destination 'platform=iOS Simulator,name=iPhone 17' \ + -only-testing:NormalTests CODE_SIGNING_ALLOWED=NO +``` +- Unit tests use Swift Testing, UI tests use XCTest. CI runs the unit tests on every PR. +- UI tests launch with `-uiTestMode -uiTestSkipOnboarding`, which stub Screen Time, NFC, + the camera and location. Other seeds are in `Normal/App/UITestSupport.swift`. +- Screen Time, NFC and real location don't work in the simulator. Say what you couldn't test. + +## Project file +Folders are synchronized groups. Target membership comes from exception lists in +`Normal.xcodeproj/project.pbxproj`: +- A new `Shared/` file used by an extension goes in that extension's + `Exceptions for "Shared" folder in "" target` list. Otherwise only the + extension fails, with "cannot find type in scope". +- A new `NormalUITests/` file goes in both of that folder's lists (`NormalUITests` + and `Normal`), or it compiles into the app. +- New `NormalTests/` files need nothing. +- Don't change `CURRENT_PROJECT_VERSION`. Version changes only touch `MARKETING_VERSION`. + +## Code +- User-facing text lives in `Normal/Resources/Localizable.xcstrings` (English only). + Xcode generates it, so don't edit it by hand. After changing text, sync it and commit + the result. This adds new strings and removes unused ones; Xcode adds the comments + when the project is next built in Xcode. + ```sh + xcodebuild -exportLocalizations -project Normal.xcodeproj -scheme Normal \ + -localizationPath /tmp/normal-loc -exportLanguage en + ``` +- Say block/unblock, not lock/unlock. +- Don't add code comments. Explain the reasoning in the PR. +- In tests, inject `now` instead of sleeping, put `.timeLimit` on tests that wait, + and save SwiftData contexts explicitly. +- Don't weaken or delete tests to make them pass. If a test needs to change, say why + in the PR. + +## Commits and PRs +- Every PR needs an issue. Link it with `Closes #N`. +- Keep changes to what the issue asks for. +- Commits are authored by the human's account only. Never add an AI as author or + co-author of a commit, including `Co-authored-by` trailers. Put + `Co-authored-by: ()` in the PR description instead. +- Fill in `.github/pull_request_template.md`. +- Changes to the areas under "Hard to reverse" in `.github/CONTRIBUTING.md` must be + agreed in the issue first. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md