| 1 |
# OxygenHub for Visual Studio Code |
| 2 |
|
| 3 |
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. |
| 4 |
|
| 5 |
## Requirements |
| 6 |
|
| 7 |
- Visual Studio Code 1.137 or later. |
| 8 |
- The **Oxygen** extension (`oxygen.oxygen-vscode`), which this one depends on, and `oxy` on your PATH. |
| 9 |
- 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. |
| 10 |
|
| 11 |
## Getting started |
| 12 |
|
| 13 |
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. |
| 14 |
2. Open a repository whose remote is on that hub. The **OxygenHub** activity bar icon shows Proposals, Issues and Releases for it. |
| 15 |
3. **Open on Remote** and **Copy Permalink** in the Oxygen extension now open pages on the hub. |
| 16 |
|
| 17 |
## Walkthroughs |
| 18 |
|
| 19 |
### Propose a change |
| 20 |
|
| 21 |
1. Commit on a bookmark other than the target. |
| 22 |
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. |
| 23 |
3. While that bookmark is current, the status bar follows the proposal's checks live. |
| 24 |
|
| 25 |
### Review a proposal |
| 26 |
|
| 27 |
1. In **Proposals**, look under **Needing me**. Expand a proposal to see its files. |
| 28 |
2. Click a file for a diff of the target against the proposal's projected state. **View Changes** opens them all. |
| 29 |
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. |
| 30 |
4. **Review…** approves, requests changes or comments. |
| 31 |
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. |
| 32 |
|
| 33 |
**Check Out Proposal** puts the projected state on a local bookmark named with `oxygenhub.proposalBookmarkPrefix`, so you can run it. |
| 34 |
|
| 35 |
### Land a proposal |
| 36 |
|
| 37 |
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. |
| 38 |
|
| 39 |
### File and work on issues |
| 40 |
|
| 41 |
- **New Issue…** opens an issue on the repository. |
| 42 |
- 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. |
| 43 |
- In **Issues**, open an issue to read it. **Comment on Issue…**, **Assign to Me**, **Close Issue** and **Reopen Issue** act on it. |
| 44 |
- Typing `#` or `@` in the commit box or a comment completes issue, proposal and user names. Hovering `#N` shows what it is. |
| 45 |
- 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. |
| 46 |
|
| 47 |
### Publish a release |
| 48 |
|
| 49 |
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. |
| 50 |
|
| 51 |
### Keep up with notifications |
| 52 |
|
| 53 |
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. |
| 54 |
|
| 55 |
## Settings |
| 56 |
|
| 57 |
|
| 58 |
|
| 59 |
| `oxygenhub.hubs` | `[]` | Base URLs of the hubs you use. Signing in adds to it, so you rarely edit it by hand. | |
| 60 |
| `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. | |
| 61 |
| `oxygenhub.proposalBookmarkPrefix` | `"proposal/"` | Prefix of the local bookmark made by **Check Out Proposal** (`proposal/12`). | |
| 62 |
| `oxygenhub.autoRefresh` | `60` | Seconds between refreshes of the views, the checks and the notification count; `0` turns it off. | |
| 63 |
| `oxygenhub.announceNotifications` | `true` | Show a message when new notifications arrive (checked on the `autoRefresh` interval). | |
| 64 |
|
| 65 |
## Building |
| 66 |
|
| 67 |
``` |
| 68 |
npm install |
| 69 |
npm run check # typecheck, bundle, and the Node tests |
| 70 |
npm run package # oxygenhub-vscode-<version>.vsix |
| 71 |
code --install-extension oxygenhub-vscode-<version>.vsix |
| 72 |
``` |
| 73 |
|
| 74 |
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. |
| 75 |
|
| 76 |
## Licence |
| 77 |
|
| 78 |
MIT or Apache-2.0, at your option, as for Oxygen itself. |