From 0ac18552763395d85acfabbf2a16d773068c06b8 Mon Sep 17 00:00:00 2001 From: Brendan Chen Date: Sun, 14 Jun 2026 23:19:07 -0400 Subject: [PATCH] Desloppify the README + remove redundant CONTRIBUTING doc --- CONTRIBUTING.md | 94 ------------------------------------------------- README.md | 78 ++++++++++++++++++++-------------------- 2 files changed, 40 insertions(+), 132 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f64f141..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,94 +0,0 @@ -# Contributing to OpenAppLock - -Thanks for your interest in OpenAppLock. This guide covers local setup, the -code-signing convention, and the branch/PR workflow. - -## Prerequisites - -- Xcode 26 or newer (the project targets **iOS 26**). -- An iOS 26 **simulator** runtime. Building and running the test suites needs - nothing else — no Apple Developer account and no code signing. - -## Code-signing setup (one time) - -Signing identity is developer-specific, so the project keeps it **outside** the -repository instead of committing a Team ID. The checked-in -[`Config/Shared.xcconfig`](Config/Shared.xcconfig) optionally includes a file -that lives one directory **above** your clone: - -``` -Developer/ -├── OpenAppLock/ <- your clone -└── SharedXcodeSettings/ - └── DeveloperSettings.xcconfig <- your settings, never committed -``` - -Because the include is optional (`#include?`), the project opens and builds for -the simulator even when that file is absent. You only need it to produce a -**signed** build or to run on a **device**: - -```sh -# from the repo root -mkdir -p ../SharedXcodeSettings -cp Config/DeveloperSettings.sample.xcconfig \ - ../SharedXcodeSettings/DeveloperSettings.xcconfig -# then edit it and set DEVELOPMENT_TEAM to your 10-character Apple Team ID -``` - -Find your Team ID at → *Membership -details*. - -### Running on your own device - -The app and its three Screen Time extensions are registered under the -maintainer's identifiers — the `dev.bchen.OpenAppLock` bundle-ID prefix and the -`group.dev.bchen.OpenAppLock` App Group — which belong to the maintainer's -team. To run on a device under your own account you must also change those to -your own: - -- `PRODUCT_BUNDLE_IDENTIFIER` for each target (app + `.Monitor`, - `.ShieldConfig`, `.ShieldAction`), -- the App Group string in `Shared/AppGroup.swift` and in the four - `*.entitlements` files, -- and request the **Family Controls** capability for your bundle IDs. - -This is only needed for on-device runs; simulator builds and tests are -unaffected. - -## Building & testing - -Open `OpenAppLock.xcodeproj` in Xcode, pick an **iOS Simulator** destination -(a device destination makes test runs hang), and build/test as usual. - -For headless/CI runs, [`Config/CI.xcconfig`](Config/CI.xcconfig) disables code -signing entirely: - -```sh -xcodebuild test \ - -project OpenAppLock.xcodeproj \ - -scheme OpenAppLock \ - -destination 'platform=iOS Simulator,name=iPhone 16' \ - -xcconfig Config/CI.xcconfig -``` - -Follow red-green TDD: for any behavior change, update -[`docs/RULES_FEATURE_SPEC.md`](docs/RULES_FEATURE_SPEC.md) first, write the -failing test, then implement. See [`AGENTS.md`](AGENTS.md) and -`docs/SWIFT_GUIDELINES.md` for the project's coding and testing standards. - -## Branch & PR workflow - -`main` advances only through reviewed pull requests — please don't push feature -or fix work to it directly. - -1. Branch from `main` using a conventional prefix: `feat/…`, `fix/…`, or - `chore/…`. -2. Make your change with tests; keep commits in - [Conventional Commits](https://www.conventionalcommits.org/) form - (`feat:`, `fix:`, `refactor:`, …). -3. Push the branch and open a PR for review. - -## License - -By contributing, you agree that your contributions are licensed under the -project's [MIT License](LICENSE). diff --git a/README.md b/README.md index 64debe6..cc7c544 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,57 @@ # OpenAppLock -OpenAppLock is an open-source iOS Screen Time app. You define recurring -**rules** that block selected apps — by schedule window, daily time limit, or -number of opens — with an optional **Hard Mode** that makes an active block -impossible to lift, edit, or delete until its window ends. The interface is -intentionally plain, native iOS (List/Form/NavigationStack). +OpenAppLock is a free, open source app blocker for iOS using Apple's Family Controls API. At this time, it has been created primarily with Claude Code. -It is built on Apple's Screen Time APIs — FamilyControls, ManagedSettings, and -DeviceActivity — so blocking is enforced by the system, not by a VPN or DNS -shim. +Join the [TestFlight](https://testflight.apple.com/join/5ymbrmns) beta! The App Store link will come...soon. -## Requirements +## Features -- Xcode 26+ and an iOS 26 simulator (to build and run the tests). -- An Apple Developer account is only needed to run on a physical device; real - app-blocking and usage tracking are observable on-device, not in the - simulator. +- Create app blocking rules + - **Schedule**: block apps on a schedule + - **Time limit**: block apps after using them for a set period of time + - **Open limit**: block apps after opening them a number of times +- Define custom app lists to use with any of these rules +- Hard mode + - If this is on, the rule cannot be disabled while it is active +- Uninstall protection + - Prevent app uninstallation to work around hard mode, if hard mode is on -## Getting started +## Building + +You need Xcode 26+ and an iOS 26 simulator to build and run the tests. To see the app blocking in action, you'll need a real device. + +You'll need to follow some steps to use your own development team/certificate/provisioning profile after cloning. + +1. Clone the repository. Do *not* open it in Xcode yet. +2. Create a folder titled `SharedXcodeSettings` *next to the cloned repository*. Then, create a file `DeveloperSettings.xcconfig` in that folder. The structure should look like this: -```sh -git clone git@github.com:brendan-ch/OpenAppLock.git -cd OpenAppLock -open OpenAppLock.xcodeproj ``` +directory/ + SharedXcodeSettings/ + DeveloperSettings.xcconfig + OpenAppLock/ # the cloned repository + OpenAppLock.xcodeproj +``` + +3. In that folder, create a file `DeveloperSettings.xcconfig` and include the following line: + +``` +DEVELOPMENT_TEAM = +``` + +4. Open the project in Xcode -Pick an **iOS Simulator** destination and build. No code signing is required -for simulator builds or tests. To run on a device, see the signing and -identifier steps in [CONTRIBUTING.md](CONTRIBUTING.md). +This setup was stolen from [NetNewsWire](https://github.com/Ranchero-Software/NetNewsWire/blob/main/README.md#building); go check them out! -## Project layout +By default, the app will attempt to read this file, falling back to an empty development team if the file doesn't exist. This will work for simulator testing, but not for real device testing. -| Path | What | -|---|---| -| `OpenAppLock/` | App target (SwiftUI + SwiftData): models, pure logic, services, views | -| `Shared/` | Code compiled into the app and all three extensions | -| `OpenAppLockMonitor/` | DeviceActivityMonitor extension (limits, resets, session expiry) | -| `OpenAppLockShieldConfig/` | ShieldConfiguration extension (shield UI) | -| `OpenAppLockShieldAction/` | ShieldAction extension (Open button handling) | -| `Config/` | Build configuration (`.xcconfig`) — see CONTRIBUTING.md | -| `docs/` | Feature spec and Swift guidelines | +Note that Xcode may also try to automatically write a development team to the `xcodeproj` file if it can't detect one. If it does this, you may need to undo that change through Git and follow the approach listed above. Note that **PRs containing hardcoded development team IDs will not be accepted**. -Deeper architecture notes live in [AGENTS.md](AGENTS.md); feature behavior is -specified in [docs/RULES_FEATURE_SPEC.md](docs/RULES_FEATURE_SPEC.md). +There's probably a better way to handle this. Please reach out using my email below, or post on the [Discussions](https://github.com/brendan-ch/OpenAppLock/discussions) section, if you have suggestions. ## Contributing -Changes land on `main` only through reviewed pull requests. Branch with a -`feat/`, `fix/`, or `chore/` prefix and open a PR — see -[CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. +If you're encountering a bug, please open an [issue](https://github.com/brendan-ch/OpenAppLock/issues) and I will look into it! For feature ideas, please raise them in the [Discussions](https://github.com/brendan-ch/OpenAppLock/discussions) section first. Because I'm still heavily developing the app, I may not accommodate all feature requests. -## License +My email is `me [at] bchen.dev` if you have any questions! -[MIT](LICENSE) © 2026 Brendan Chen