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.
- 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.
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.
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.
A drop is a small set of files with its own history, on the hub, with an address you can pass on.
50
51
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.
52
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.
53
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.
54
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.
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.
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.
63
64
###Approve, expedite and read reports in Flow
65
66
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.
67
68
###Start a repository
69
70
**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.
**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.
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.
79
80
##Settings
81
82
| Setting | Default | What it does |
83
|---|---|---|
84
|`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.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. |
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.
104
105
##Licence
106
107
MIT or Apache-2.0, at your option, as for Oxygen itself.