Help: getting started filled in for this hub, delegation, pipelines and stamps, the keyboard, and a glossary for people coming from GitHub 43e8ca33bc5d

//! `/help` (hub spec §6.3): getting started with this hub's own address,

//! remote name and certificate filled in, the keyboard, and a glossary

//! for people coming from GitHub.

use super::repo::Quickstart;

use super::{Page, Shell};

use crate::auth::Viewer;

use crate::Shared;

use askama::Template;

use axum::extract::State;

#[derive(Template)]

#[template(path = "help.html")]

pub struct HelpPage {

    shell: Shell,

    q: Quickstart,

    base: String,

    /// The signed-in user, or a placeholder, for example URLs.

    who: String,

}

pub async fn help(State(app): State<Shared>, viewer: Viewer) -> Page<HelpPage> {

    let shell = Shell::new(&app, "/help", &viewer);

    let who = shell.user.clone().unwrap_or_else(|| "OWNER".into());

    let base = app.config.base_url().trim_end_matches('/').to_string();

    Page(HelpPage { shell, q: Quickstart::new(&app, true), base, who })

}

impl HelpPage {

    /// Trust this hub's certificate, when it is self-signed (empty otherwise).

    pub fn ca_setup(&self) -> String {

        match &self.q.ca_url {

            Some(url) => format!("mkdir -p ~/.config/oxy\ncurl -fsSL {url} -o {}", self.q.ca_file),

            None => String::new(),

        }

    }

    /// An example repository address on this hub.

    pub fn repo_url(&self) -> String {

        format!("{}/{}/REPOSITORY", self.base, self.who)

    }

    pub fn delegate_cmd(&self) -> String {

        format!("curl -fsSL {}/.well-known/oxyhub-key -o hub.identity\noxy identity delegate add hub.identity", self.base)

    }

    pub fn clone_cmd(&self) -> String {

        let url = self.repo_url();

        match &self.q.ca_url {

            Some(_) => format!("OXY_CA={} oxy clone {url}", self.q.ca_file),

            None => format!("oxy clone {url}"),

        }

    }

}

{% extends "base.html" %}

{% block title %}Help{% endblock %}

{% block content %}

<div class="head"><h1>Help <small>using {{ shell.site }}</small></h1></div>

<div class="sectioned help">

<nav class="section-nav" aria-label="Sections">

  <a href="#start">Getting started</a>

  <a href="#identity">Your identity</a>

  <a href="#push">Pushing</a>

  <a href="#clone">Cloning</a>

  <a href="#proposals">Proposals</a>

  <a href="#delegate">Letting the hub act for you</a>

  <a href="#flow">Pipelines</a>

  <a href="#keys">Keyboard</a>

  <a href="#glossary">Coming from GitHub</a>

</nav>

<div class="sections">

<section class="panel" id="start">

  <h2>Getting started</h2>

  <p>{{ shell.site }} hosts <strong>Oxygen</strong> repositories. You work with them through <code>oxy</code>, the Oxygen client; the hub shows them, reviews them and runs their pipelines. Every command below is filled in for this hub.</p>

  <ol>

    <li>Install <code>oxy</code>: build it from the <code>oxygen</code> repository with <code>cargo build --release</code> and put <code>target/release/oxy</code> on your path.</li>

    <li>Say who you are and make a signing identity (next section).</li>

    <li>{% if shell.user.is_some() %}Create a <a href="/settings/tokens">personal access token</a>{% else %}<a href="/register">Register</a>, then create a personal access token under Settings › Tokens{% endif %} with <code>repo:write</code>. It is shown once; keep it in <code>oxy</code>'s configuration, not in scripts.</li>

    <li>{% if shell.user.is_some() %}<a href="/new">Create a repository</a>{% else %}Create a repository with <strong>+ NEW</strong>{% endif %} and push to it (below). An empty repository shows the same commands, with its own address.</li>

  </ol>

  <p class="small mute"><code>oxy doctor</code> checks your identity, configuration and remotes, and says what to do about any problem.</p>

</section>

<section class="panel" id="identity">

  <h2>Your identity</h2>

  <p>Oxygen changes are signed. Your identity is a key pair (Ed25519 with ML-DSA-65) kept under <code>~/.config/oxy</code>; the public part travels with your changes.</p>

  {% let cmd = "oxy config --user author.name \"Your Name\"\noxy config --user author.email [email protected]\noxy identity create\noxy config --user core.sign change" %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>Link the key to your account under {% if shell.user.is_some() %}<a href="/settings/keys">Settings › Keys</a>{% else %}Settings › Keys{% endif %}: the page gives you a challenge to sign with <code>oxy identity sign-challenge</code>, which proves you hold the key. Linked keys show on your profile, and the hub can then tell which signed changes are yours.</p>

</section>

<section class="panel" id="push">

  <h2>Pushing</h2>

  {% let ca = self.ca_setup() %}

  {% if !ca.is_empty() %}

  <p>This hub uses a self-signed certificate. Save it once, and point each remote at it:</p>

  <div class="cmds"><pre><code>{{ ca }}</code></pre><button class="small" data-copy="{{ ca }}">copy</button></div>

  {% endif %}

  <p>From a checkout, add the repository as a remote, give it your token, and push:</p>

  {% let cmd = q.connect(self.repo_url().as_str()) %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>An empty repository takes its identity from the first push, so every later clone shares it. <code>oxy push {{ q.remote }}</code> sends the current bookmark; <code>oxy push {{ q.remote }} --bookmark NAME</code> another one. Tags travel with pushes.</p>

  <p class="small mute">A Git history comes across with <code>oxy git import --branch main path/to/git-checkout NAME</code>: every commit becomes a change, and the result can be pushed like any other repository.</p>

</section>

<section class="panel" id="clone">

  <h2>Cloning</h2>

  {% let cmd = self.clone_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>Public repositories clone without a token. For private ones, and to push back, set <code>oxy config remote.origin.token YOUR-TOKEN</code>{% if q.ca_url.is_some() %} and <code>oxy config remote.origin.ca {{ q.ca_file }}</code>{% endif %} in the clone. <code>oxy pull origin</code> brings in what others pushed; there is no merge commit, because Oxygen changes combine by themselves.</p>

</section>

<section class="panel" id="proposals">

  <h2>Proposals</h2>

  <p>A proposal asks for a bookmark's changes to be added to another bookmark, like a pull request. Push your bookmark, then open one from the repository's Proposals tab, from the compare page's <strong>Propose this</strong>, or from a fork.</p>

  <ul>

    <li>A proposal is always tested and reviewed on its <strong>projected state</strong>: exactly what the target will hold once it lands. It never goes stale, and there is nothing to rebase.</li>

    <li>Review comments are anchored to lines' atoms, so they stay on the right line through later pushes.</li>

    <li>An approval can be a <strong>seal</strong>: your signature over the proposal's changes (<code>oxy seal</code>), which anyone can check offline.</li>

    <li>Land from the page, or from a client with <code>oxy proposal land URL</code>, which signs the landing with your own key.</li>

  </ul>

</section>

<section class="panel" id="delegate">

  <h2>Letting the hub act for you</h2>

  <p>Edits in the browser and landings from the proposal page are changes too, and they must be signed. The hub signs them as your <strong>delegate</strong>, only if you allow it. Allowing it is a one-off step:</p>

  {% let cmd = self.delegate_cmd() %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>Then link your identity again under Settings › Keys, so the hub sees the delegation. You can withdraw it at any time with <code>oxy identity delegate remove</code>; a repository's trust policy still decides whether a delegated change may update a bookmark.</p>

</section>

<section class="panel" id="flow">

  <h2>Pipelines</h2>

  <p>Pipelines run in <strong>OxygenFlow</strong>. Put a pipeline in <code>.flow/pipeline.kdl</code> and push: each job runs in its own microVM with no network, and its result shows on the repository's Flow tab and as a check named <code>flow/JOB</code> on proposals. A site administrator enables Flow for a repository.</p>

  <p>Instead of a badge, a README can carry a <strong>state stamp</strong>:</p>

  {% let cmd = "[![flow](.flow/stamp)](.flow/run)" %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p>It shows the result for the state you are looking at (a tag shows the tag's result), names that state, and carries each job's receipt hash.</p>

</section>

<section class="panel" id="keys">

  <h2>Keyboard</h2>

  <table class="list">

    <tbody>

      <tr><td><kbd>/</kbd></td><td>Search</td></tr>

      <tr><td><kbd>g</kbd> <kbd>c</kbd></td><td>The repository's code</td></tr>

      <tr><td><kbd>g</kbd> <kbd>h</kbd></td><td>History of the bookmark you are on</td></tr>

      <tr><td><kbd>g</kbd> <kbd>p</kbd></td><td>Proposals</td></tr>

      <tr><td><kbd>g</kbd> <kbd>i</kbd></td><td>Issues</td></tr>

      <tr><td><kbd>g</kbd> <kbd>b</kbd></td><td>Bookmarks</td></tr>

      <tr><td><kbd>g</kbd> <kbd>t</kbd></td><td>Trust</td></tr>

      <tr><td><kbd>y</kbd></td><td>Replace the address with a permalink to this exact state (files and trees)</td></tr>

      <tr><td>click a line number, <kbd>Shift</kbd>-click another</td><td>Select lines; copy them or a permalink to them</td></tr>

      <tr><td><kbd>?</kbd></td><td>The keyboard sheet</td></tr>

    </tbody>

  </table>

</section>

<section class="panel" id="glossary">

  <h2>Coming from GitHub</h2>

  <table class="list glossary">

    <thead><tr><th>GitHub</th><th>Here</th><th>What is different</th></tr></thead>

    <tbody>

      <tr><td>commit</td><td><strong>change</strong></td><td>A change records edits, not a snapshot, and names the changes it depends on. Changes that do not touch the same lines combine in any order with the same result, so there are no merge commits. A change keeps its identity when it is rebased or squashed.</td></tr>

      <tr><td>commit SHA, tree</td><td><strong>state</strong></td><td>The files a set of changes makes. A state is addressed by its heads (<code>a1b2…+c3d4…</code>); checks, stamps and permalinks belong to states.</td></tr>

      <tr><td>branch</td><td><strong>bookmark</strong></td><td>A name for a state. It can have several <strong>heads</strong> (changes nothing else depends on); the tree is their union, not a conflict.</td></tr>

      <tr><td>tag</td><td><strong>tag</strong></td><td>An immutable named state, usually signed.</td></tr>

      <tr><td>merge, rebase</td><td><code>oxy merge</code>, <code>oxy pull</code></td><td>Uniting bookmarks adds the other side's changes. Nothing is rewritten and no merge change is made.</td></tr>

      <tr><td>merge conflict</td><td><strong>conflict</strong> in the state</td><td>A conflict is recorded in the history instead of blocking you. It stays visible (the Conflicts tab) until a change resolves it, and anyone can resolve it later.</td></tr>

      <tr><td>pull request</td><td><strong>proposal</strong></td><td>Reviewed and tested on its projected state. It cannot go stale, and approvals can be signed seals.</td></tr>

      <tr><td>branch protection</td><td><strong>trust policy</strong></td><td>Signed rules in the repository itself: who may move which bookmark, with how many signatures. Every client enforces them, not only the hub.</td></tr>

      <tr><td>Actions, CI badge</td><td><strong>OxygenFlow</strong>, state stamp</td><td>Jobs run in microVMs on exact states; results are receipts, and the stamp says which state they belong to.</td></tr>

      <tr><td>git blame</td><td><strong>blame</strong></td><td>Exact through rebases and squashes: each line is an atom with one authoring change, so there is no "ignore revisions" file.</td></tr>

      <tr><td>fork</td><td><strong>fork</strong></td><td>A copy under your name with its own identity and bookmarks, sharing the stored objects. Its proposals go upstream as <code>you/name:bookmark</code>; the upstream's trust policy is not copied.</td></tr>

      <tr><td>personal access token</td><td><strong>token</strong></td><td>For pushing and the API. Your signing key is what proves authorship; a token only authorises.</td></tr>

    </tbody>

  </table>

</section>

</div>

</div>

{% endblock %}

pub mod help;

        .route("/help", get(help::help))

    // Help, filled in for this hub (hub spec §6.3).

    let help = page(&h.app, "/help").await;

    assert!(help.contains(&format!("oxy remote add hub {}/OWNER/REPOSITORY", h.base)), "commands carry this hub's address");

    assert!(help.contains(&format!("oxy clone {}/OWNER/REPOSITORY", h.base)));

    assert!(help.contains(&format!("curl -fsSL {}/.well-known/oxyhub-key -o hub.identity", h.base)), "the delegation recipe");

    assert!(!help.contains("oxyhub-ca.pem"), "no certificate step for a hub without a self-signed certificate");

    for id in ["start", "identity", "push", "clone", "proposals", "delegate", "flow", "keys", "glossary"] {

        assert!(help.contains(&format!("id=\"{id}\"")) && help.contains(&format!("href=\"#{id}\"")), "section {id}");

    }

    assert!(help.contains("<strong>bookmark</strong>") && help.contains("<strong>proposal</strong>"), "glossary");

    assert!(home_has_help(&page(&h.app, "/explore").await), "linked from every page");

}

fn home_has_help(page: &str) -> bool {

    page.contains("<a href=\"/help\">Help</a>")

| `/help` | Getting started with this hub's own address, remote name and certificate filled in (identity, pushing, cloning, proposals, delegating to the hub, pipelines and stamps), the keyboard, and a glossary for people coming from GitHub. Linked from the header band, the footer and the keyboard sheet |

  <a href="/help">Help</a>

      <div><h3>Use</h3><a href="/help">Help</a><a href="/explore">Explore</a><a href="/api/v1/repos">API</a><a href="/.well-known/oxyhub-key">Hub key</a></div>

  <p class="small"><a href="/help#keys">All keys</a> · <a href="/help">Help</a></p>

/* Help (hub spec §6.3). */

.help section.panel { padding: 16px 20px; scroll-margin-top: 14px; }

.help section.panel h2 { margin-top: 0; }

.help ol, .help ul { padding-left: 1.3em; }

.help li { margin: 4px 0; }

table.glossary td:first-child { white-space: nowrap; color: var(--mute); }

table.glossary td:nth-child(2) { white-space: nowrap; }