From 2020c85064ea8081c6d03183c1d1a58b25544520 Mon Sep 17 00:00:00 2001 From: Koray Guler Date: Mon, 9 Nov 2026 04:00:55 +0300 Subject: [PATCH] Docs: decisions log in docs/, product rules only; neutral tooling wording in the research notes --- .gitignore | 2 +- DECISIONS.md | 20 -------------------- docs/DECISIONS.md | 20 ++++++++++++++++++++ docs/RESEARCH.md | 6 +++--- docs/VERIFICATION.md | 4 ++-- 5 files changed, 26 insertions(+), 26 deletions(-) delete mode 100644 DECISIONS.md create mode 100644 docs/DECISIONS.md diff --git a/.gitignore b/.gitignore index 4cfd95a7..417d1eaf 100644 --- a/.gitignore +++ b/.gitignore @@ -17,5 +17,5 @@ PRODUCT.md .playwright-cli/ artifacts/ -# Licensed keyword research exports (Semrush); keep local, never commit +# Licensed keyword research exports; keep local, never commit research/semrush/ diff --git a/DECISIONS.md b/DECISIONS.md deleted file mode 100644 index a9cf4135..00000000 --- a/DECISIONS.md +++ /dev/null @@ -1,20 +0,0 @@ -# Decisions - -One dated line per decision, oldest first. When a decision replaces an earlier one, the line says which. If another project file contradicts this log, this log wins; fix the other file. - -- 2026-10-17: Bun for everything: installation, scripts, tests, Astro and CI. -- 2026-10-17: Source-available apps are listed, but marked separately on cards, explained on product pages, and filterable by source. They are never called open source. -- 2026-10-17: Every app's official icon may be shown, including reserved-trademark and non-commercial ones, unmodified and with its real terms recorded. An icon is removed if its rights holder asks. -- 2026-10-17: Design follows the Mac App Store: sidebar shell (bottom tab bar on mobile), Discover shelves, product pages with a Get button, light and dark appearance from the system. Replaces the dark showcase, which had replaced the rejected pastel library design. -- 2026-10-29: Product name OpenMacApps, domain openmacapps.com, repository koative/openmacapps. Every page states that Mac and macOS are Apple trademarks and that the site is not affiliated with Apple. -- 2026-10-29: Pages say "free" only when every app they list has `freeDownload: true`. -- 2026-11-02: Credit koative only; the founder's name and personal link are not shown. Replaces the 2026-10-31 credit that also named the founder. -- 2026-11-06 (Koray): Brand mark is the blue squircle with a 2×2 app grid and the top-right tile lifted out (`docs/BRAND.md`). Replaces the blue square with a cube. -- 2026-11-06 (Koray): Inclusion rules: unmaintained apps are listed with an Unmaintained label; star counts are not a criterion; command-line-only tools and apps whose main job needs a paid account stay out. -- 2026-11-06 (Koray): Standard published source-available licenses that allow personal use are listed (Commons Clause, FSL, PolyForm Noncommercial, Perimeter and Shield, the CC BY-NC family, and BSL when its Additional Use Grant allows ordinary use). One-off custom licenses stay out, apart from the reviewed exceptions in `src/lib/catalog.ts`. -- 2026-11-07: claude-seo (core skills, v2.5.0, keyless only) is the SEO tool for this project. Copy work may also use the copywriting, copy-editing, competitors and site-architecture skills from marketingskills. geo-seo-claude is not used: its schema templates ship filled-in ratings and it updates itself from an unpinned branch. Whatever these tools suggest, structured data never gains `aggregateRating`, `Review` or `Rating` markup; `bun run check:links` fails the build output if it does. -- 2026-11-07: Nothing is pushed straight to `main`. Every change goes on its own branch and reaches `main` through a pull request. Commits from this workstation are authored as Abdulkadir Polat. -- 2026-11-08 (Koray): Prose app counts stay round ("1,800+", "More than 1,800"), computed from the catalog so they stay true as it grows. Exact counts remain where the page lists the apps. -- 2026-11-08: App descriptions must read as written by a careful human editor. The house style in CONTRIBUTING.md ("Writing the description") applies: the app in third person, the reader as "you", facts only from primary sources, no stock frames or puffery, at most two attributions. `src/lib/writing.ts` enforces the mechanical rules on every record verified from this date. The owner approved rewriting all thin descriptions, most-installed first, after a 20-record pilot. -- 2026-11-08: When sources disagree on a requirement such as the minimum macOS, the project's download page or release notes win. -- 2026-11-08: Paid SEO and writing tools the owner subscribes to (Semrush, Quetext and others) may be used through his browser session. Their raw exports stay out of Git. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 00000000..d078bbb3 --- /dev/null +++ b/docs/DECISIONS.md @@ -0,0 +1,20 @@ +# Decisions + +One dated line per project decision, oldest first. When a decision replaces an earlier one, the line says which. If another file in this repository contradicts this log, the log wins; fix the other file. + +- 2026-10-17: Bun for everything: installation, scripts, tests, Astro and CI. +- 2026-10-17: Source-available apps are listed, but marked separately on cards, explained on product pages, and filterable by source. They are never called open source. +- 2026-10-17: Every app's official icon may be shown, including reserved-trademark and non-commercial ones, unmodified and with its real terms recorded. An icon is removed if its rights holder asks. +- 2026-10-17: Design follows the Mac App Store: sidebar shell (bottom tab bar on mobile), Discover shelves, product pages with a Get button, light and dark appearance from the system. Replaces the dark showcase, which had replaced the rejected pastel library design. +- 2026-10-29: Product name OpenMacApps, domain openmacapps.com, repository koative/openmacapps. Every page states that Mac and macOS are Apple trademarks and that the site is not affiliated with Apple. +- 2026-10-29: Pages say "free" only when every app they list has `freeDownload: true`. +- 2026-11-02: Credit koative only; no personal names or links. Replaces the 2026-10-31 credit that also named the founder. +- 2026-11-06: Brand mark is the blue squircle with a 2×2 app grid and the top-right tile lifted out (`docs/BRAND.md`). Replaces the blue square with a cube. +- 2026-11-06: Inclusion rules: unmaintained apps are listed with an Unmaintained label; star counts are not a criterion; command-line-only tools and apps whose main job needs a paid account stay out. +- 2026-11-06: Standard published source-available licenses that allow personal use are listed (Commons Clause, FSL, PolyForm Noncommercial, Perimeter and Shield, the CC BY-NC family, and BSL when its Additional Use Grant allows ordinary use). One-off custom licenses stay out, apart from the reviewed exceptions in `src/lib/catalog.ts`. +- 2026-11-07: Structured data never carries `aggregateRating`, `Review` or `Rating` markup, because the catalog has no ratings or reviews; `bun run check:links` fails the build output if it does. +- 2026-11-07: Every change reaches `main` through a pull request; nothing is pushed to `main` directly. +- 2026-11-08: Prose app counts stay round ("1,800+", "More than 1,800"), computed from the catalog so they stay true as it grows. Exact counts remain where the page lists the apps. +- 2026-11-08: App descriptions follow the house style in CONTRIBUTING.md ("Writing the description"): the app in third person, the reader as "you", facts only from primary sources, no stock frames or puffery, at most two attributions. `src/lib/writing.ts` enforces the mechanical rules on every record verified from this date. +- 2026-11-08: When sources disagree on a requirement such as the minimum macOS, the project's download page or release notes win. +- 2026-11-09: Public copy never claims that licenses were checked "by hand"; it says what the check is: the license is read from the license file. diff --git a/docs/RESEARCH.md b/docs/RESEARCH.md index 0e6c1f32..a867f08a 100644 --- a/docs/RESEARCH.md +++ b/docs/RESEARCH.md @@ -219,7 +219,7 @@ have not been reviewed yet. 25 apps were added, chosen by search demand rather than by directory listings alone. -- **Leads.** Semrush showed which alternatives and "for Mac" pages people search for but which listed only two apps. GitHub data (stars, license, latest release, macOS assets) then filtered the 182 discovery leads first listed after 2026-10-17 (a release in the last year, an OSI license and a macOS asset). +- **Leads.** Search data showed which alternatives and "for Mac" pages people search for but which listed only two apps. GitHub data (stars, license, latest release, macOS assets) then filtered the 182 discovery leads first listed after 2026-10-17 (a release in the last year, an OSI license and a macOS asset). - **Apps that strengthen searched pages:** Pinta, Netcatty, FileZilla, Nextcloud Desktop, Seafile, Mattermost Desktop, Proton Pass, Skim, Friction, AndroidFileSync, Mac Android Subsystem, ntfsmac, Peel, Apache OpenOffice and AFFiNE. - **Other well-maintained apps:** Arroxy, Prism Download Manager, TagStudio, Textus, KeyEcho, RuSwitcher, SpreadPaper, FolderForge, Shiyin and magpie. - **New alternatives pages** these apps made possible: Transmit, Dropbox, After Effects, Android File Transfer, Punto Switcher and 4K Video Downloader. @@ -290,9 +290,9 @@ have not been reviewed yet. 826 apps were added in one pass, after the inclusion rules changed on 2026-11-06: unmaintained apps are listed with an Unmaintained label, star counts are not a criterion, command-line-only tools and apps whose main job needs a paid account stay out. - **Leads.** The 533 remaining leads from awesome-swift-macos-apps (the pilot's prefilter, plus Compositor back in now that stars do not count) and the 1,192 older leads every earlier expansion had turned down. GitHub data kept 626 of the older ones: not archived, not a fork, a detected license, and a macOS release asset or a project website, with no age limit. -- **Review.** A script gathered each lead's metadata, license text, README, releases and icon paths into a dossier. Sub-agents judged 1,153 leads from the dossiers against CONTRIBUTING.md: 889 accepted, 56 held, 208 rejected. Other sub-agents then wrote the entries, re-reading every license file, checking the README and, where the download finished, the build with `spctl` and `stapler`. Where a download could not be checked, the record says only what the project states. +- **Review.** A script gathered each lead's metadata, license text, README, releases and icon paths into one file per lead. Each lead was then judged against CONTRIBUTING.md: 1,153 leads, 889 accepted, 56 held, 208 rejected. Writing each entry meant re-reading the license file, checking the README and, where the download finished, the build with `spctl` and `stapler`. Where a download could not be checked, the record says only what the project states. - **Added:** 826 apps, 69 of them marked Unmaintained and 6 source available; 639 have their own icon. -- **Final review.** A second set of sub-agents read every new record, its license text and its icon. Their findings removed 26 records and 20 icons and corrected about 60 records (license identifiers, unmaintained labels, contradictory claims). +- **Final review.** A second pass read every new record, its license text and its icon. It removed 26 records and 20 icons and corrected about 60 records (license identifiers, unmaintained labels, contradictory claims). - **Held out at final review:** - **Fork or derivative of a listed app:** AutoPrompter (Textream), Hummingbird (Easy Move+Resize), RktMachine (CoreOS VM), Threadlines (T3 Code), WindowHop (AltTab), Yank (Buffer). - **Main job needs a paid account or license:** Push Notifications (Apple Developer Program), Superagent (a paid AI plan), Ping Warden (Ping Protection is $15), Ring Stats (current Oura rings need a membership). diff --git a/docs/VERIFICATION.md b/docs/VERIFICATION.md index 150af5af..5a1723fd 100644 --- a/docs/VERIFICATION.md +++ b/docs/VERIFICATION.md @@ -215,11 +215,11 @@ The build takes about 10 s. `bun run check:links` passes (86,533 links). ## Search-data pass: verified "free" wording and Windows-only products — 2026-10-29 -**Why.** Semrush US data (kept locally in the ignored `research/semrush/`) showed that "free" searches far outnumber "open source" ones: 7,620 against 610 for Lightroom alternatives, and 37,340 against 1,010 for Photoshop. It also showed high demand for Windows-only tools on the Mac, such as "notepad++ for mac" (3,600) and "rufus mac" (1,300). +**Why.** US search-volume data (licensed, kept out of Git) showed that "free" searches far outnumber "open source" ones: 7,620 against 610 for Lightroom alternatives, and 37,340 against 1,010 for Photoshop. It also showed high demand for Windows-only tools on the Mac, such as "notepad++ for mac" (3,600) and "rufus mac" (1,300). **Free downloads.** Every app record now has `freeDownload`, set from evidence: 869 are free and 9 paid. - **GitHub release assets (694 apps):** a script found a macOS installer in each app's official GitHub releases. -- **Agents (184 apps):** checked each official download page or App Store listing. +- **Official pages (184 apps):** each official download page or App Store listing was checked. - **Paid:** Ardour, Fritzing, Automute, AI Dictation, Mac Mouse Fix, Pi Stats, QCAD, Textual and Zettel. Paid binaries, paid store-only builds and trials that must be bought all count as paid. - **Wording:** product pages say "Free download" or "Paid download". 130 of 154 guide pages qualify for "Free, open-source" in their titles, because every app they list is free.