3d15fc50e8
* docs(agents): require reviews to ask if a feature earns its place * test(sync): guard against required fields added without a migration A required field added to a persisted model without a backfill migration breaks every existing install: data already on disk lacks it, and typia rejects it. The failure is latent — hydration trusts a snapshot whose schema version matches, so it only surfaces when an unrelated bump later drags it onto the migration path. #8965 shipped in January and detonated in v18.15.0 as a deterministic boot-to-empty-store (#9124). Nothing at runtime complains at the time the mistake is made, so only a test catches it. frozen-state-v18.15.json is a frozen snapshot of the persisted state shape as written by v18.15, run through migrateState -> validateFull. It stands in for data on users' disks and must never be regenerated from current defaults. Every slice carries at least one entity: typia cannot check an entity type whose collection is empty, so a fixture with `entities: {}` would validate no matter how the model changed — and issue-provider configs, where this class historically clusters, would have been the blind spot. Sabotage-verified on two slices by adding a required field to the model AND its DEFAULT_* (which compiles clean, as #8965 did): Project and RedmineCfg both fail the guard with the exact missing-field path. Note: typia inlines the model graph into validation-fn.ts, but Angular's build cache does not invalidate that file when a type it only imports changes — a warm-cache local run can report zero errors against a stale validator. CI builds cold. Documented in the spec docblock. Refs #9125, #9124 * test(sync): close coverage holes in the frozen-state guard Multi-agent review found the guard was thinner than its own docblock claimed, and that two pieces of its guidance were wrong. Coverage — the docblock asserted "every slice carries at least one entity", but eight collections were empty, so their element types were never shape-checked at all: reminders, pluginUserData, pluginMetadata, planner.days, timeTracking.project/tag, task.attachments, metric.reflections and both archive task collections. Populated all of them. issueProvider covered only the 8 built-in keys; the 6 migrated plugin-shaped members (GITHUB, CLICKUP, GITEA, LINEAR, TRELLO, AZURE_DEVOPS) and a plugin: provider are exactly what sits on disk after the issue-provider→plugin migration, so all 15 union members are now present. Jira/OpenProject availableTransitions are populated too — that field caused one of the historical occurrences. validateFull omits archiveOld/archiveYoung (DataToValidate), so a new required ArchiveModel field could ship green. Both are now validated explicitly via validateAppDataProperty. The emptiness invariant is now enforced rather than asserted in prose: a spec walks the fixture and fails on any collection that is empty everywhere it appears (per element TYPE, not per instance; *Ids lists are exempt as primitives). It caught four gaps the manual pass missed. Guidance — the regeneration advice was backwards. A transforming migration is NOT a reason to edit the fixture: migrateState applies it during the test, and the spec still passing is the proof the migration handles real v18.15 data. Hand-editing to the post-migration shape while the pin stays at 4 would re-apply the migration to already-migrated data. Also: a failed migration no longer falls through to validate undefined, and the failure message now carries the "do NOT edit the fixture" instruction, since the message is the only thing a developer reads before reaching for the quickest fix. AGENTS.md rule 11 had three inaccuracies: the per-section config merge covers 9 of 21 sections (not all config), the blanket globalConfig auto-fix runs only inside dataRepair rather than normal hydration, and "entity slices heal nothing" ignored the generic boolean/nullable coercions. It also pointed at recreate-fallback.const.ts, where membership additionally opts a type into SPAP-14 disjoint-field auto-merge — an unrelated sync behaviour change. Rewritten instruction first, and now prefers optional typing over a backfill migration, which rule 10 discourages because it costs a schema bump. A credential sentinel guards the one path by which this file could ever leak secrets: regeneration against a real profile. Re-sabotaged after the rewrite (RedmineCfg, cold cache): still fires. Refs #9125, #9124 * test(sync): regression-lock the #9124 idle backfill The guard cited #9124 but could not catch a regression of it. With the fixture pinned at schema 4 (== CURRENT_SCHEMA_VERSION), migrateState early-returns, so no migration ran: deleting the backfill in lww-replacement-barrier-v2-to-v3.ts left the whole spec green. Adds the case that closes it — v18.14 data is the frozen state at schema 2 minus the field #8965 added, so migrating it must backfill the field and still validate. Derived from the same frozen bytes rather than a second 900-line fixture: identical coverage, no duplication. This is also the only case exercising the migration chain until the next schema bump. Sabotage-verified the way the previous cases were: removing the backfill fails with "Expected undefined to be false". Also runs prettier over the fixture — .husky/pre-commit runs pretty-quick --staged, so an unformatted fixture would have handed the next contributor a several-hundred-line reformat diff on a file whose whole value is being reviewable. Refs #9125, #9124 * test(sync): clone the frozen fixture before migrating it migrateState returns `state` BY REFERENCE when source === target (migrate.ts early-out), so migrateFrozen() handed every spec in the file a live handle on the imported module singleton. Harmless today — all consumers are read-only — but one stray mutation would corrupt the fixture for whatever ran next, and that is an order-dependent flake this repo has been bitten by before. structuredClone costs well under a millisecond on 24KB. Also records a verified detail about the stale-validator caveat: clearing only the `babel-webpack` cache namespace is NOT sufficient. Measured both ways against a live sabotage — the narrow clear still reported green against a model that genuinely broke the fixture, because the typia output is cached under `angular-webpack`. Refs #9125 * test(sync): make the vacuity check explicit instead of heuristic The walk-based version inferred which empty collections were acceptable from a regex on the path name (`*Ids` = primitive list) plus a group-by-name rule. That was wrong in a way that mattered: a future OBJECT array named `somethingIds` would have been waved through silently, which is the exact failure mode this check exists to prevent. Replaced with an explicit list of the paths that must stay populated, plus a path lookup. A missing or renamed path now resolves to undefined and reports as empty, so the check fails loudly rather than silently skipping — fail-safe in the direction that matters. This is NOT a size reduction (194 -> 196 lines); the 22 explicit paths cost about what the heuristic cost. It buys auditability — a reviewer can read exactly what is covered — and removes the misclassification risk. Sabotage-verified: emptying `reminders` and `issueProvider.entities` (what regenerating the fixture from createValidAppData would do, the likeliest way this guard dies) fails the check. Refs #9125 |
||
|---|---|---|
| .agents/skills/commit-messages | ||
| .air | ||
| .codex | ||
| .devcontainer | ||
| .github | ||
| .husky | ||
| .signpath/policies/super-productivity | ||
| .vscode | ||
| android | ||
| build | ||
| docs | ||
| e2e | ||
| electron | ||
| eslint-local-rules | ||
| fastlane | ||
| ios | ||
| nginx | ||
| packages | ||
| scripts | ||
| snap/hooks | ||
| src | ||
| tools | ||
| .browserslistrc | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.example | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| .gitpod.yml | ||
| .npmrc | ||
| .nvmrc | ||
| .prettierignore | ||
| .prettierrc.json | ||
| .stylelintrc.mjs | ||
| AGENTS.md | ||
| angular.json | ||
| ARCHITECTURE-DECISIONS.md | ||
| capacitor.config.ts | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| docker-compose.e2e.fast.yaml | ||
| docker-compose.e2e.yaml | ||
| docker-compose.supersync.yaml | ||
| docker-compose.yaml | ||
| docker-entrypoint.sh | ||
| Dockerfile | ||
| Dockerfile.e2e.dev | ||
| Dockerfile.e2e.dev.fast | ||
| electron-builder.yaml | ||
| eslint.config.js | ||
| funding.json | ||
| Gemfile | ||
| Gemfile.lock | ||
| LICENSE | ||
| ngsw-config.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| SECURITY.md | ||
| tsconfig.base.json | ||
| tsconfig.json | ||
| webdav.yaml | ||
An advanced todo list app with timeboxing & time tracking capabilities that supports importing tasks from your calendar, Jira, GitHub and others
🌐 Open Web App or 💻 Download
💻 Downloads & Install
For all current downloads, package links, and platform-specific notes:
check the wiki
✔️ Features
- Keep organized and focused! Plan and categorize your tasks using sub-tasks, projects and tags and color code them as needed.
- Use timeboxing and track your time. Create time sheets and work summaries in a breeze to easily export them to your company's time tracking system.
- Helps you to establish healthy & productive habits:
- A break reminder reminds you when it's time to step away.
- The anti-procrastination feature helps you gain perspective when you really need to.
- Need some extra focus? A Pomodoro timer is also always at hand.
- Collect personal metrics to see, which of your work routines need adjustments.
- Integrate with Jira, Trello, GitHub, GitLab, Gitea, OpenProject, Linear, ClickUp and Azure DevOps. Auto import tasks assigned to you, plan the details locally, automatically create work logs, and get notified immediately, when something changes.
- Basic CalDAV integration.
- Back up and synchronize your data across multiple devices with Dropbox and WebDAV support
- Attach context information to tasks and projects. Create notes, attach files or create project-level bookmarks for links, files, and even commands.
- Super Productivity respects your privacy and does NOT collect any data and there are no user accounts or registration. You decide where you store your data!
- It's free and open source and always will be.
And much more!
Note
The web version has some limitations: See the Web App vs Desktop comparison for more details.
📖 Documentation and Guides
Getting Started
- Getting started guide (article)
- Video walkthrough (YouTube)
- Eat the frog prioritizing scheme
Starting Point in Wiki:
First steps •
Reference •
How-To
Productivity Tips:
Keyboard Shortcuts •
Short Syntax
Need Help?
Visit the discussions page
See the bottom of the README for more information on the documentation.
Advanced Topics
Here are some other topics covered in the official wiki:
Development:
Run dev server •
Package the app •
Build for Android •
Run with Docker
Data Management:
User Data •
Issue Providers •
Sync Providers
Customization:
Plugins •
Themes
APIs:
Sync Server •
Plugins •
REST
Community
The development of Super Productivity is driven by a wonderful community of users and contributors. Thank you all so much for your support!
👀 Check out our awesome curated list of community-created resources about Super Productivity
♥️ Contributing
If you want to get involved, please check out the CONTRIBUTING.md
There are several ways to help.
-
Spread the word: More users mean more people testing and contributing to the app which in turn means better stability and possibly more and better features. You can vote for Super Productivity on Slant, Product Hunt, Softpedia or on AlternativeTo, you can tweet about it, share it on LinkedIn, reddit or any of your favorite social media platforms. Every little bit helps!
-
Provide a Pull Request: Here is a list of the most popular community requests and here some info on how to run the development build (wiki). Please make sure that you're following the commit message format and to also include the issue number in your commit message, if you're fixing a particular issue (e.g.:
feat: add nice feature #31). -
Answer questions: You know the answer to another user's problem? Share your knowledge!
-
Provide your opinion: Some community suggestions are controversial. Your input might be helpful and if it is just an up- or down-vote.
-
Provide a more refined UI spec for existing feature requests
-
Make a feature or improvement request: Something can be done better? Something essential missing? Let us know!
-
Translations, Icons, etc.: You don't have to be a programmer to help; learn how to contribute translations!
-
Create custom plugins or custom themes
Special Thanks to our Sponsors!!!
Recently support for Super Productivity has been growing! A big thank you to all our sponsors!
(If you are, intend to or have been a sponsor and want to be shown here, please let me know!)
Code Signing
Windows binaries are signed. Free code signing is provided by SignPath.io, certificate by SignPath Foundation.
Documentation: Manual versus Automated
There are two wikis: the official one hosted in by GitHub and the autonomously generated variant using DeepWiki.com. The manually curated version is a more stable and approachable resource designed to help you understand the app from a more human-focused perspective whereas DeepWiki is optimized for explaining the code itself with little regard for context beyond that.
Official Wiki
It is preferable to maintain local documentation rather than rely on an external service. It also preferable that the documentation is updated in tandem with the code changes as demonstrated in this commit.
Changes to files within ./docs/wiki are linted in CI before being automatically
sync'd to the repository's official Wiki hosted by GitHub.
Migrating to Docusaurus is a long-term goal once the content and structure of the wiki has matured and the remaining "legacy docs" have either been reworked or removed. There are some automations in development to help reduce the difference between the published docs and the state of the code while retaining a human-in-the-loop.
DeepWiki.com
If you have very specific questions about how the code works or why a bug might be producing
a particular message it might be useful to
. It can help "cite your sources" when discussing functionality and code that you don't fully
understand as part of feature requests or bug reports.
This automated reference does come with some significant drawbacks:
- Intent: Describes what code does, not why decisions or tradeoffs were made.
- Staleness: Will *always* lag behind the code.
- Code-Focused: Does not provide guides or conceptual explanations.
- Cost: Potential future cost and higher resource usage than static docs.