OXYGENHUB
◆ main oxygenhub-vscode / README.md
7.3 KiB · Markdown · last changed OxygenHub 0.13.0: Drops in the editor with Share as a Drop (closes #7); Flow approvals, expedite, reports, timings and test results (closes #8); ready/draft, landable, trust reports, asset downloads and new repositories (closes #9) 6 days ago renderedsource blame history raw

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

  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, Releases, Flow, Diffusion and Drops for it, and Flow's test reports appear in the Testing view.
  3. Open on Remote and Copy Permalink in the Oxygen VCS 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.

Share code as a drop

A drop is a small set of files with its own history, on the hub, with an address you can pass on.

  1. Select some lines in an editor and choose Share as a Drop… from its right-click menu (or an editor tab's menu, for the whole file). In the Explorer, Share Files as a Drop… takes one or more files or a folder.
  2. Give it a title and choose Secret (unlisted: anyone with its address can read it) or Public (listed on your Drops page). Its address is copied for you.
  3. In Drops, click a file to open it; saving it commits a new change to the drop. A drop's menu adds or removes files, changes its title, makes it public or secret, copies its link, its oxy clone command or the HTML to embed it, clones it, and shows or adds comments.
  4. Open a Drop… takes someone's drop by its address, to read it, Star it, comment on it or Fork it into a drop of your own.

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.

Check a release's trust

On a release in Releases, Show Trust Report shows who signed the tag and the changes, which OxygenFlow build made each asset, and the audit's verdicts. Save Asset… downloads an asset, with your token when the repository is private.

Approve, expedite and read reports in Flow

A job waiting on its approval rules shows a shield in Flow: Approve Job or Reject Job… decides it. A queued or running run's menu has Expedite Run… (say why; it goes ahead of the queue) and Cancel Run. A job's tooltip says how long it waited and where its time went; Show Reports… lists what it published.

Start a repository

New Repository… (the Proposals view's … menu) creates one under you or an organisation. When you say what it is for and the owner has an assistant, it can draft the starting files. Then it is cloned where you choose.

See what Diffusion is doing

Diffusion lists what each repository takes from (the subrepos it pins) and who takes from it, each with the hub's status in words (untested │ passes), how far behind it is and its open bump proposal. Pick a row to open the bump.

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

SettingDefaultWhat it does
oxygenhub.hubs[]Base URLs of the hubs you use. Signing in adds to it, so you rarely edit it by hand.
oxygenhub.flowPollSeconds5How often the Flow view and its status bar item look again while a run is queued or running; once a minute otherwise.
oxygenhub.dropVisibility"secret"Which Share as a Drop offers first: secret or public.
oxygenhub.copyDropLinktrueCopy a new drop's address to the clipboard.
oxygenhub.flowNotificationstrueSay 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.autoRefresh60Seconds between refreshes of the views, the checks and the notification count; 0 turns it off.
oxygenhub.announceNotificationstrueShow 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.