README as walkthroughs by task with a settings table, dated changelog entries, and a test that the docs keep up with the manifest e04950748142

// The documentation keeps up with the manifest: every setting is described

// in the README, and the CHANGELOG has a dated entry for this version.

import { test } from "node:test";

import assert from "node:assert/strict";

import { readFileSync } from "node:fs";

const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

const readme = readFileSync(new URL("../README.md", import.meta.url), "utf8");

const changelog = readFileSync(new URL("../CHANGELOG.md", import.meta.url), "utf8");

test("every setting is documented in the README's Settings table", () => {

  const cfg = pkg.contributes.configuration;

  const props = (Array.isArray(cfg) ? cfg : [cfg]).flatMap((c) => Object.keys(c.properties ?? {}));

  assert.ok(props.length > 0);

  const table = readme.slice(readme.indexOf("## Settings"));

  const missing = props.filter((p) => !table.includes("| `" + p + "` |"));

  assert.deepEqual(missing, [], "settings missing from the README");

});

test("the CHANGELOG's newest entry is this version, and every entry is dated", () => {

  const headings = [...changelog.matchAll(/^## (.+)$/gm)].map((m) => m[1]);

  assert.match(headings[0], new RegExp("^" + pkg.version.replace(/\./g, "\\.") + " \\(\\d{4}-\\d{2}-\\d{2}\\)$"));

  const undated = headings.filter((h) => !/^\d+\.\d+\.\d+ \(\d{4}-\d{2}-\d{2}\)$/.test(h));

  assert.deepEqual(undated, [], "entries without a version and date");

});

## 0.6.2 (2026-09-28)

## 0.6.1 (2026-09-28)

## 0.6.0 (2026-09-28)

## 0.5.0 (2026-09-28)

## 0.4.0 (2026-09-28)

## 0.3.0 (2026-09-28)

## 0.2.0 (2026-09-28)

## 0.1.2 (2026-09-27)

## 0.1.1 (2026-09-27)

## 0.1.0 (2026-09-27)

Proposals, reviews, issues, releases and checks from an OxygenHub, in the editor. It builds on the Oxygen extension the way the GitHub Pull Requests extension builds on the built-in Git extension. The specification is `docs/spec.md` in this repository.

## Requirements

- Visual Studio Code 1.137 or later.

- The **Oxygen** extension (`oxygen.oxygen-vscode`), which this one depends on, and `oxy` on your PATH.

- An account on an OxygenHub, and a personal access token from it (Settings › Tokens on the hub). `repo:write` covers everything here; `repo:read` is enough to browse.

## Getting started

1. Run **OxygenHub: Sign in**, give the hub's URL (for example `https://earth.example.org:7343`) and paste the token. The token is kept in VS Code's secret storage, never in settings.

2. Open a repository whose remote is on that hub. The **OxygenHub** activity bar icon shows Proposals, Issues and Releases for it.

3. **Open on Remote** and **Copy Permalink** in the Oxygen extension now open pages on the hub.

## Walkthroughs

### Propose a change

1. Commit on a bookmark other than the target.

2. Run **Propose Current Bookmark…** and pick the target bookmark, then give a title. The bookmark is pushed for you, and the new proposal opens on the hub, where you can write its description.

3. While that bookmark is current, the status bar follows the proposal's checks live.

### Review a proposal

1. In **Proposals**, look under **Needing me**. Expand a proposal to see its files.

2. Click a file for a diff of the target against the proposal's projected state. **View Changes** opens them all.

3. Hover in the diff and choose **Start Review Thread** to comment on a line. Threads are anchored to atoms (Oxygen's content-addressed lines), so they follow their lines when the proposal is rebased. **Reply** and **Resolve** work in place.

4. **Review…** approves, requests changes or comments.

5. To approve with your key, run **Seal My Approval**. It runs `oxy seal --proposal` in a terminal, so the signature is made on your machine.

**Check Out Proposal** puts the projected state on a local bookmark named with `oxygenhub.proposalBookmarkPrefix`, so you can run it.

### Land a proposal

When the requirements are met (approvals, checks, no conflicts), **Land Proposal** lands it through `oxy` in a terminal, with your own key. **Close Proposal** closes it without landing.

### File and work on issues

- **New Issue…** opens an issue on the repository.

- Select code, or put the cursor on a `TODO` line, and run **New Issue from Selection…**. The issue quotes the code and links to it.

- In **Issues**, open an issue to read it. **Comment on Issue…**, **Assign to Me**, **Close Issue** and **Reopen Issue** act on it.

- Typing `#` or `@` in the commit box or a comment completes issue, proposal and user names. Hovering `#N` shows what it is.

- A change message with `closes #N` closes that issue when it lands on the default bookmark. Any other `#N` puts the change on that issue's timeline.

### Publish a release

In **Releases**, run **Draft Release…** and pick a tag. The notes are drafted from the changes since the previous release; edit them before publishing. Each release lists its assets.

### Keep up with notifications

The status bar shows how many notifications are unread. **Open Inbox** lists them, and each opens its proposal or issue in the editor. New ones are announced unless `oxygenhub.announceNotifications` is off.

## Settings

| Setting | Default | What it does |

|---|---|---|

| `oxygenhub.hubs` | `[]` | Base URLs of the hubs you use. Signing in adds to it, so you rarely edit it by hand. |

| `oxygenhub.proposalBookmarkPrefix` | `"proposal/"` | Prefix of the local bookmark made by **Check Out Proposal** (`proposal/12`). |

| `oxygenhub.autoRefresh` | `60` | Seconds between refreshes of the views, the checks and the notification count; `0` turns it off. |

| `oxygenhub.announceNotifications` | `true` | Show a message when new notifications arrive (checked on the `autoRefresh` interval). |

## Building

```

npm install

npm run check          # typecheck, bundle, and the Node tests

npm run package        # oxygenhub-vscode-<version>.vsix

code --install-extension oxygenhub-vscode-<version>.vsix

```

The hub client tests start a real hub from `../oxygenhub/target/release/oxygenhub` when that binary exists. `src/hubapi.d.ts` is generated by OxygenHub (`make ts` there); copy it over when the API changes.

## Licence

MIT or Apache-2.0, at your option, as for Oxygen itself.