docs: MkDocs Material site + first ADR#9
Merged
Merged
Conversation
The treemap was redesigned from a rectangular layout to a radial sunburst, but the tests still asserted on the old TreemapCell.rect API and no longer compiled. Rewrite the 12 tests against the radial model (startAngle/endAngle/ innerRadius/outerRadius), preserving each test's original intent. Also fix a ByteFormatter expectation that assumed binary (1024^3) units when the formatter defaults to decimal SI units. All 20 tests in the suite now pass via 'swift test'.
…cache) Adds .github/workflows/ci.yml: a matrixed build-test job across macos-14 and macos-15, run on every push to main and every PR. Steps: SwiftPM cache (.build + ~/Library/Caches/org.swift.swiftpm keyed on Package.resolved), 'swift build -v' (serves as the static-analysis gate via StrictConcurrency), then 'swift test'. Also declares Sparkle 2.9.1 in Package.swift (and pins Package.resolved). The source does 'import Sparkle' but the dependency had only been declared in the Xcode project, so 'swift build'/'swift test' failed from the command line and would fail in any SPM-based CI. No Linux/lint matrix: this is a macOS-only SwiftUI app, so it cannot build on Linux runners.
Adds the GitHub Actions CI badge to the README header and docs/ci-journal.md, which documents the workflow, three real bugs found while making the suite compile, and why 'act' cannot reproduce a macOS job locally (act uses Linux Docker containers; there is no macOS container image).
The first CI run was red on macos-14 and macos-15: GlassCompat used glassEffect / .buttonStyle(.glass), which exist only in the macOS 26 SDK (Xcode 26 / Swift 6.2). 'if #available(macOS 26, *)' is a runtime check and does not stop the compiler from needing the symbol, so the build failed on older SDKs (and cascaded into ContentView, which calls the helpers). It compiled locally only because this machine has the macOS 26 SDK, a textbook 'works on my machine' bug, which is exactly what the OS matrix is for. Wrap each macOS-26-only call in '#if compiler(>=6.2)' so older toolchains compile only the NSVisualEffectView fallback; the runtime #available stays inside the new-SDK branch so an Xcode-26 build still back-deploys to macOS 14/15. Documented in docs/ci-journal.md.
macos-14 cannot build the app: it uses MeshGradient (macOS 15 SDK) and glassEffect (macOS 26 SDK), so the macOS 14 SDK lacks both symbols. The app requires the macOS 15+ SDK to compile (runtime back-deploy to macOS 14 is handled separately via #available). Settle on macos-15 (Xcode 16 / Swift 6.1, fallback compile path) + macos-26 (Xcode 26 / Swift 6.2, real Liquid Glass path). Journal updated with the finding.
Adds a Diátaxis-structured docs site (tutorial, how-to, reference) built with MkDocs Material, deployed via GitHub Actions to GitHub Pages at /guide/ alongside the existing landing page. Also adds the first ADR recording why Liquid Glass call sites need a compile-time #if compiler(>=6.2) guard in addition to the runtime #available check.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
guide/(MkDocs Material): one tutorial, one how-to guide, and reference docs forByteFormatterandTreemapLayout, each kept to one Diátaxis mode..github/workflows/pages.ymlto GitHub Pages at/guide/, alongside (not replacing) the existing landing page at/. Repo Pages source is switched from legacy Jekyll to Actions-based build to allow this.docs/adr/0001-compile-time-guard-for-liquid-glass.md, the first ADR, capturing why Liquid Glass call sites need#if compiler(>=6.2)in addition to runtime#available(the bug the Week 5 CI matrix caught).Stacked on #8 (Week 5 CI branch), since this branch is based on
ci/tests-and-actionsand the docs workflow lives alongside it. Vale + CI (Week 6 task 4) will follow on top of this branch.Test plan
mkdocs build --strictpasses locally with no warnings./guide/, both verified present.