OxygenHub for Visual Studio Code

Proposals, reviews, issues, releases and checks from an OxygenHub, in the editor. It builds on the Oxygen VCS extension (oxygenhub.oxygen-vscode) 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 (oxygenhub.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

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.
Open a repository whose remote is on that hub. The OxygenHub activity bar icon shows Proposals, Issues and Releases for it.
Open on Remote and Copy Permalink in the Oxygen VCS extension now open pages on the hub.

Walkthroughs

Propose a change

Commit on a bookmark other than the target.
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.
While that bookmark is current, the status bar follows the proposal's checks live.

Review a proposal

In Proposals, look under Needing me. Expand a proposal to see its files.
Click a file for a diff of the target against the proposal's projected state. View Changes opens them all.
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.
Review… approves, requests changes or comments.
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.flowPollSeconds`	`5`	How often the Flow view and its status bar item look again while a run is queued or running; once a minute otherwise.
`oxygenhub.flowNotifications`	`true`	Say when an OxygenFlow run finishes, with a way to a failed job's log.
`oxygenhub.caFiles`	`{}`	CA certificate files for hubs with self-signed certificates, by base URL. A checkout whose remote names a CA (`remote.NAME.ca`, which `oxy` uses too) needs no entry: the extension takes it from the remote.
`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.

OxygenHub VCS

OxygenHub.io