diff options
Diffstat (limited to 'docs/usage.html')
| -rw-r--r-- | docs/usage.html | 36 |
1 files changed, 36 insertions, 0 deletions
diff --git a/docs/usage.html b/docs/usage.html index 4fbb7cb..017f6e4 100644 --- a/docs/usage.html +++ b/docs/usage.html @@ -286,6 +286,42 @@ pi -p --no-session --no-tools --mode json --model gemma4:31b-cloud \ <p style="color:var(--dim);font-size:.9rem">The mirror only fast-forwards, so <code>git pull --ff-only</code> can never wedge. Nothing here can push — the repository refuses <code>receive-pack</code> at three levels.</p> +<h2 id="contributing">Contributing (contrib branches)</h2> +<p>The mirror accepts contributions, but only as <strong>contrib branches</strong> — <code>main</code> is +generated from the platform's monorepo and a push to it would be erased by the next publish. Pushes go to +a separate host that asks for credentials; the read-only host in your <code>origin</code> stays anonymous +and read-only.</p> +<pre><code># 1. one token per account, issued by the platform operator +# (looks like: https://<user>:wx11gp_…@push.newos.webx11.duckdns.org/newos4.git) +git remote add push https://push.newos.webx11.duckdns.org/newos4.git + +# 2. work on a branch, push it under contrib/ +git switch -c contrib/my-fix +git commit -am "fix(shell): handle an empty command" +git push push HEAD:refs/heads/contrib/my-fix</code></pre> +<p style="color:var(--dim);font-size:.9rem">Use a credential helper rather than pasting the token into the +URL of a repository you might publish. Git will ask once and can remember it +(<code>git config --global credential.helper store</code> writes it to a plain file — choose +<code>cache</code> or your OS keychain if that matters).</p> + +<h3>What the server enforces</h3> +<table> + <tr><th>Rule</th><th>Reason</th></tr> + <tr><td>Only <code>refs/heads/contrib/*</code></td><td><code>main</code> and tags are generated by the publisher; a push there would disappear at the next publish</td></tr> + <tr><td>No credentials in the diff</td><td>The repository is public. Every added blob is scanned before it is accepted; a match rejects the whole push with the file name</td></tr> + <tr><td>No profile or key files</td><td><code>.user.json</code>, <code>.session</code>, <code>.env</code>, <code>*.pem</code>, <code>id_rsa</code> are refused by path</td></tr> + <tr><td>≤ 200 files, ≤ 2 MB of new content per push</td><td>Keeps one push from making the mirror unusable</td></tr> + <tr><td>Deleting your own contrib branch</td><td>Allowed — it is your branch</td></tr> +</table> + +<h3>What happens after you push</h3> +<p>A moderator triages every branch automatically: docs-only changes are marked <em>ready</em>, anything +touching code is queued for a human with a diff summary, and a branch that breaks a hard rule is deleted. +The queue is visible to the operator; you will hear back on your branch, not in a black hole.</p> +<pre><code>git fetch push 'refs/heads/contrib/*:refs/remotes/contrib/*' +git log --oneline main..contrib/my-fix # what your branch adds +git push push --delete contrib/my-fix # withdraw it</code></pre> + <h2 id="updating">Updating later</h2> <pre><code>cd newos4 git pull --ff-only # the mirror only ever fast-forwards |