Magic Apps

Documentation

macmagic.app

Engineering workflow

All work is tracked in GitHub Issues, GitHub's native sub-issues and GitHub Projects v2, on the Magic Apps (Project #1) board.

graph TD
    M["Milestone"] --> E1["Epic (type:epic)"]
    M --> E2["Epic (type:epic)"]
    E1 --> S1["Sub-issue"]
    E1 --> S2["Sub-issue"]
    S1 -.-> PR["Pull request: Closes #N"]
    PR == Merged ==> Done["Issue closed, epic progress updated"]

Epics

An Epic is a parent tracking issue for a large feature theme or architectural initiative. It holds no code of its own; break the work into child sub-issues with GitHub's native sub-issues, and GitHub recalculates the epic's percentage complete as they close.

Issues

A sub-issue is one executable unit of work, linked to a parent Epic. A standalone issue is a discrete bug or self-contained task that belongs to no Epic. Every issue carries:

  1. A clear problem statement and technical acceptance criteria.
  2. A milestone naming the target release phase.
  3. Labels from the taxonomy below.

Milestones

Both apps ship together, so the milestones cover the project rather than either app.

Milestone Answers
Alpha Can a build run on someone else's Mac? Signed, notarised, hand-delivered, no updater
Private Beta Can it update them without breaking the install? The same testers, now self-updating
Public Beta Can anyone find it? Free download from the site, no gate
1.0 Does the licence check hold? The check and the pages it depends on
Post-Launch Everything that does not gate a release

A closed issue carries the milestone of the phase it shipped in. Merged PRs follow their issue.

Specs

For complex new functionality, or a change big enough that the approach is not obvious, write the spec before the code and commit it under specs/<app>/. The spec records the approach, what it does not cover, and any major decision whose reason is not obvious.

Open the spec as its own pull request and get it reviewed before implementation starts. Agreeing the design first is cheaper than reviewing code written to a design nobody else settled on, and an agent implementing the change works from the agreed spec rather than from the issue prose.

../../specs/README.md indexes the specs. When the subsystem ships, its spec is rewritten into the living docs and deleted; the writing-docs skill carries the rules for what a spec holds.

Label taxonomy

Tag issues and PRs with at least one label from each relevant category:

Category Labels Description
Type type:epic, type:feature, type:bug, type:infra, type:ci, type:research What kind of work this is.
Area area:css-theming, area:native-swift, area:memory-perf, area:extensions, area:compose, area:search, area:licensing Subsystem affected.
App app:magimail, app:magical, app:core Target application or shared package.
Priority priority:p1-urgent, priority:p2-important, priority:p3-normal Urgency and scheduling order.

Pull requests and branching

Always branch off the latest main:

Link the target issue in the PR description with GitHub's closing keyword:

## Summary

Fixes right-sidebar CSS selector scoping to prevent hiding main navigation.

Closes #<issue-number>

Never close an issue by hand when a PR resolves it. The automation closes the issue and advances the epic's progress as soon as the PR merges into main.

Project board automations

The board runs three built-in automations:

  1. Auto-Add: every new issue in alxhslm/magic-apps lands on the board under Todo.
  2. PR Opened: opening a PR that links an issue (e.g. Closes #<issue-number>) flips that issue's Status from Todo to In Progress.
  3. PR Merged: when the PR merges into main, GitHub closes the issue, marks it Done on the board, and increments the completion bar on its parent Epic.

Board views