Shared Tasks 0.4.0

Shared Tasks 0.4.0: share a whole section of a note.

Requires Obsidian 1.13.4 or later, as 0.3.2 did.

New: shared sections

• "Share section…". Put the cursor on a heading, or under it, and share
  the heading with everything under it: tasks, subtasks, paragraphs and
  lists, in order, down to the next heading of the same or a higher level.
  • A preview shows exactly what will be shared, and what under the
    heading stays private on your device.
  • Each section is a collaboration of its own, with its own key and its
    own invitation.
  • Whatever is added inside the section later is shared too.
• Joining. Your collaborator runs "Join collaboration" with the
  one-time link, then "Insert shared section…" in any note of theirs. Their
  other text stays private.
• Status marks. A double tick (✓✓) after a shared heading means
  "shared". A separate icon shows sync progress, for example "Saved
  locally; waiting to sync", "Offline; local updates will wait" or "Needs
  your attention". Click it, or run "Open shared section details", to see
  the details: the status, what is shared, and who has access, as last
  verified with the server.
• Conflicts. A task moved to two places, or a field changed on both
  sides, shows as "Needs your attention". "Go to next shared section
  problem" finds it; "Review conflicts…" in the details lets you choose.
  Nothing is lost while a choice is open.
• Removing access. "Remove access…" in the details removes someone's
  future access and gives the section a new key. Copies they already
  received cannot be erased, and the confirmation says so. On their side,
  the section says the sync server no longer accepts their changes; their
  new edits stay on their device.
• Detach this section. Stops sharing a section in one note and keeps its
  text as your own. The shared section, your other notes and your
  collaborators are unchanged.
• Copying. "Copy readable text (without sharing metadata)" copies the
  text without the section's markers. "Copy shared section" copies it with
  them: pasted into another note, it is another copy of the same section,
  and it gives nobody access.
• Repair. "Repair shared sections in this note" puts a damaged boundary
  back, points to lines it cannot match, and lets you choose between your
  version and the shared one.
• Moving 0.3 shared tasks into a section is an explicit copy offered by
  "Share section…". "Restore note before section import" undoes it in the
  note.

In the note, a section carries one comment after its heading, one at its
end and one beside each item. Live Preview hides them; Source mode, or
"Show or hide sharing metadata", shows them.

Shared sections are on in 0.4.0 and in its betas: nothing to turn on.

• The 0.3 preview setting is gone. "sectionsPreview" in the plugin's
  data.json no longer does anything, whether true or false; the next
  save of the settings drops it.
• To turn shared sections off, quit Obsidian, add
  "sectionsDisabled": true to .obsidian/plugins/shared-tasks/data.json,
  and start it again. Shared tasks (0.3) work as before either way.

Also new

• "Export diagnostics…" prepares a report of versions, states and error
  codes, and shows it to you in full first. It holds no note text, names,
  paths, keys or invitation links. You copy it or save it as a file;
  nothing is sent.
• Local sync data is encrypted at rest on each device, under a key kept
  on that device. "Rotate key" (Settings → Shared Tasks → "Local
  encryption") replaces it.
• New members catch up faster. The owner's plugin publishes Snapshots,
  so a new member loads one plus the latest changes, not the whole history.
• After a server restore, a member the server had forgotten gets back in
  by themselves.

Limits

• Size. A section of about 200 tasks with their notes is the qualified
  size. A much larger one (2,000 tasks) works, but each edit blocks the
  editor for seconds.
• Long history. After many thousands of edits, a section becomes slower
  (about half a second per edit). The details show how large its history
  is; past about 200,000 characters they suggest starting a new section for
  new material. Nothing happens automatically; compacting a section's
  history is planned after this release.
• Project server quotas. The project server (sync.openlfcp.org)
  currently lets one identity host up to 200 collaborations (each shared
  section is one), up to 50 new ones a day from one network, 256 MiB of
  stored data per identity and 128 MiB per collaboration (the server holds
  3 GiB in all). Past a limit, the action is refused with "quota
  exceeded"; nothing already shared is lost.
  These values may change, and the server's operator can set other limits
  for an identity. A server you run yourself sets its own.
• Mobile. Sections are read-only on mobile: they arrive and are shown,
  and your edits there stay on your device. "Share section…", inviting and
  removing access are not offered. Shared tasks work there as before.
• No headings inside a section. Sharing offers to split it into
  sections.
• Local tokens. Some Tasks-plugin tokens stay local to your note (🔁 🛫
  ➕ ❌ 🔼). The preview shows them.
• Desktop platforms. Windows and macOS are checked by an automated
  smoke test in CI on each release. The plugin has not been tried by hand
  on Windows, nor with an input method (IME) for languages such as
  Chinese, Japanese or Korean.
• A pilot with users follows this release. 0.4.0 was tested by the
  project; feedback from the first users may bring 0.4.x fixes.

Updating from 0.3

Updating to 0.4. Your shared tasks keep working as before. Shared
Tasks upgrades its sync data on this device the first time 0.4 starts: it
is encrypted at rest, and earlier versions can no longer open it.

Going back. After updating to 0.4, Shared Tasks cannot go back to
0.3.x on this device: its local sync data is upgraded and encrypted.
Downgrade only to 0.4.x or later. Your notes are not affected. If a 0.3.x
plugin shows "Shared Tasks could not start: VersionError", that is why:
install 0.4.x again, and its data is intact.

A collaborator still on 0.3.x cannot join a shared section: their plugin
says a newer version is needed, without using up the link.

Since the last betas (0.4.0-beta.16 to 0.4.0-beta.20)

For testers on the betas:

• Updating from Shared Tasks 0.3.4 now always starts syncing. Updated
  in the same Obsidian window (as Obsidian's own plugin update and BRAT
  do), the new version could find the old one's data still in use and fail
  to start: nothing synced, sections stayed on "Loading shared section",
  and nothing said why until Obsidian was restarted. It now waits for the
  old version to finish and tries again for a few seconds. If the vault
  really is open in another Obsidian window, it says so once and starts by
  itself when that window closes.
• A start that fails says so. For any other reason, one notice says
  "Shared Tasks could not start: …" and what to do (restart Obsidian; your
  notes are not affected), instead of staying silent.
• A note open only in Reading view shows a collaborator's changes. If
  a note with a shared section was open only in Reading view, a
  collaborator's changes never appeared in it, although the section said
  it was up to date, and switching back to editing lost them from your
  note. They now show in Reading view and stay when you switch back; the
  collaborator's change is never undone.
• A section stays fast as its history grows. In a section where tasks
  had been deleted, each change took longer the more the section had been
  edited: after a few thousand changes, a second or more. It now stays
  about as fast as in a new section, and its memory stays flat however
  long its history is. A two-hour soak with three editors kept a change's
  typical time at about 100 ms through about 5,000 changes.
• A new member who can't insert a section yet is told what to do.
  "Insert shared section…" said only that the section "cannot be shown
  here yet". It now says the section has a conflict to resolve first: ask
  a member who already has it in a note to open its details and choose
  "Review conflicts…", then insert it again.
• New tasks next to an unresolved conflict are saved. While a conflict
  waited for "Review conflicts…", new tasks typed next to it could fail
  with "Local save failed", and every task typed after them too. They are
  now placed next to the nearest task that can take them, and saved.
• Moving a task by cut and paste keeps it whole. Cut with Shift+↓ from
  the start of a task's line when the next task is nested, the nested task
  now keeps its place and indentation, and the pasted task does not push
  the one it lands on under it. A task's whole line selected with the
  mouse and cut now takes its hidden link line along, so the paste restores
  the same task; deleted with Backspace or Delete, the task is removed for
  your collaborators too.
• Tested before release: installing and updating on Obsidian 1.13.4
  and 1.14.4: a fresh install, an update from 0.3.4 and from
  0.4.0-beta.15, turning the plugin off and on, and reinstalling it. The
  details are in the
  support matrix.
• Tested before release: themes, views and copying on Obsidian 1.13.4
  and 1.14.4, with a collaborator editing: light and dark theme in Source,
  Live Preview and Reading view, split view, the Tasks plugin on and off,
  and tasks copied into a note outside any section. Also in the
  support matrix.

Under the hood

• The TypeScript SDK is @openlfcp/* 0.2.0 (exact versions, from npm with
  provenance).
• Spec mvp-0.2-baseline.12; the project server runs the reference server
  0.3.2, unchanged by this release.
• On start, Shared Tasks takes the vault's writer lock before it opens
  its local database, waits for an older version's connection to close
  (up to about 10 seconds), and keeps retrying in the background while
  another window holds the lock. A native test updates from 0.3.4 and from
  0.4.0-beta.15 on each supported Obsidian version.
• The OpenLFCP MVP 0.2 release notes:
  mvp-0.2-release-notes.md.

Install and upgrade

From Community plugins (Settings → Community plugins → Updates), with BRAT
(openlfcp/obsidian), or by hand: put main.js, manifest.json and
styles.css from the release page into
<vault>/.obsidian/plugins/shared-tasks/. Your identity, collaborations and
settings are kept. How to use sections:
shared sections guide.