Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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: <agent> (<model>)` 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).
22 changes: 22 additions & 0 deletions .github/SECURITY.md
Original file line number Diff line number Diff line change
@@ -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
12 changes: 12 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
Closes #

## What and why

## How it was tested
<!-- Tests added or run, a screen recording for UI changes, and what you couldn't test. -->

## AI use
<!-- Tools used and for what, or "None". If an agent wrote code, add:
Co-authored-by: <agent> (<model>) -->

- [ ] Touches a "Hard to reverse" area in CONTRIBUTING.md, agreed in the issue
59 changes: 59 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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>" 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: <agent> (<model>)` 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.
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
@AGENTS.md