.gitbay/wiki/Parity.org

  1#+title: Parity
  2
  3Which surface can do what. The CLI is meant to be the complete
  4interface: every capability exists over SSH, and the other surfaces
  5dispatch the same control commands rather than reimplementing them, so
  6they cannot drift. This page is updated in the merge request that
  7changes a row.
  8
  9Three surfaces now: the CLI over SSH, the web, and the iOS client
 10(krz/gitbay-ios). A =no= in the cli column is a defect, not a
 11preference — it means some surface reached around the registry and
 12stranded a capability where only it can reach.
 13
 14* Rule
 15
 16A capability lands over SSH first. If it belongs to the
 17triage/review/respond loop, it lands on the web in the same merge
 18request. Anything whose input is a credential — secrets, mirror
 19tokens, API tokens — stays SSH-only by design: the web dispatcher
 20refuses =SSHOnly= commands outright. Session minting is not one of
 21them: what a browser submits to ask for a login link is a username or
 22an address, and the credential it gets back travels by mail.
 23
 24Rows are one page or one action each. Grouped rows hide gaps, twice
 25now: "browse, log, blame, search" read as covered while blame had no
 26command at all, and "build list, log" read as covered while the job
 27list a trigger can name had none (krz/gitbay#50), leaving the picker
 28browser-only and the iOS build screen unable to say more than the log.
 29
 30* Merge requests
 31
 32| capability             | cli | web | ios |
 33|------------------------+-----+-----+-----|
 34| read, diff, commits    | yes | yes | yes |
 35| review and check times | yes | yes | yes |
 36| who resolved it, when  | yes | yes | yes |
 37| comment                | yes | yes | yes |
 38| edit title and body    | yes | yes | yes |
 39| review (approve etc.)  | yes | yes | yes |
 40| resolve a thread       | yes | yes | yes |
 41| comment on a diff line | yes | yes | yes |
 42| merge (all strategies) | yes | yes | yes |
 43| close                  | yes | yes | yes |
 44| create                 | yes | yes | yes |
 45| draft, ready           | yes | yes | no  |
 46| search title and body  | yes | yes | no  |
 47| create from a fork     | yes | no  | yes |
 48| retarget               | yes | yes | no  |
 49| milestone              | yes | yes | yes |
 50| choose body markup     | yes | no  | no  |
 51| stacked merge requests | yes | yes | no  |
 52
 53Reviews and checks carry the time they last said something, and a
 54=ci/<job>= check carries how long its build ran, so a merge request
 55reads without opening the build. Statuses posted through =status set=
 56have no build and report only the time. A merged or closed merge
 57request names who resolved it and when; a row without that stamp — a
 58=migrate= import, or one merged before krz/gitbay!137 with no
 59=mr.merged= event to backfill from — says neither rather than
 60inventing a time.
 61
 62A merge request whose target is another open merge request's source
 63branch is stacked on it: =mr show= and the page say so both ways, and
 64when the lower one merges, everything stacked on it is retargeted onto
 65what it merged into with its reviews kept. A squash or rebase merge is
 66refused while anything is stacked on the merge request, since it would
 67rewrite the commits the stack builds on. The iOS client renders the
 68retarget but has no stack view yet.
 69
 70A draft merge request is open but not asking: it does not merge, and it
 71does not appear in anyone's review queue. Draft is a flag rather than a
 72fifth state, so every =state = 'open'= rule still means what it did.
 73Batched review and range-diff (krz/gitbay#111) are not built.
 74
 75Nothing asks a *particular* person for a review. The review queue is
 76computed from involvement — what you own, are granted, or reach through
 77an org or team — so a collaborator with write access who has not touched
 78a thread hears nothing until they do (krz/gitbay#145).
 79
 80Creating from a fork works anywhere the source can be typed as
 81=owner/name:branch=; only the web lacks it. Retargeting moves an open
 82merge request onto another branch of the same repository and stales the
 83reviews, since an approval was of the diff against the old branch.
 84
 85* Issues
 86
 87| capability          | cli | web | ios |
 88|---------------------+-----+-----+-----|
 89| read, list, filter  | yes | yes | yes |
 90| filter by label, assignee, author, milestone | yes | yes | no |
 91| search title and body | yes | yes | no |
 92| create              | yes | yes | yes |
 93| comment             | yes | yes | yes |
 94| edit title and body | yes | yes | yes |
 95| close and reopen    | yes | yes | yes |
 96| labels, assignees   | yes | yes | yes |
 97| milestone           | yes | yes | yes |
 98| milestone list      | yes | yes | yes |
 99| labels: list, colour | yes | no  | no  |
100| choose body markup  | yes | no  | no  |
101
102Labels are created on the fly by =issue label --add= and managed by
103=label list=, =label set <label> --color rrggbb= and =label remove=,
104which takes the label off every issue. The web paints the stored colour
105on every chip and derives one from the name when none is set; it has no
106form for setting one yet.
107
108Issue, MR and release bodies, and their comments, carry the markup they
109were written in — =--format md|org= on create, comment and edit, stored
110alongside the text so changing a preference later cannot reinterpret
111prose that already exists. Every surface *renders* the stored format;
112the =no= above is the absence of a picker on the web form and in the iOS
113composer, both of which write markdown. Diff-line comments have no
114format column and are always markdown.
115
116* Repositories
117
118| capability                  | cli | web | ios |
119|-----------------------------+-----+-----+-----|
120| browse files                | yes | yes | yes |
121| read a file                 | yes | yes | yes |
122| commit log                  | yes | yes | yes |
123| commit log at a ref         | yes | yes | yes |
124| one commit with its patch   | yes | yes | yes |
125| blame                       | yes | yes | yes |
126| search file contents        | yes | yes | yes |
127| compare two refs            | yes | yes | no  |
128| branches and tags           | yes | yes | yes |
129| wiki (read)                 | yes | yes | yes |
130| download an archive         | yes | yes | n/a |
131| edit a file                 | yes | yes | yes |
132| create                      | yes | yes | yes |
133| pin                         | yes | yes | yes |
134| watch, mute                 | yes | yes | no  |
135| settings, protection        | yes | yes | yes |
136| topics, website             | yes | yes | yes |
137| visibility                  | yes | yes | yes |
138| archive (read-only flag)    | yes | yes | yes |
139| release list, show          | yes | yes | yes |
140| release create, edit        | yes | yes | yes |
141| build list                  | yes | yes | yes |
142| build show (one build)      | yes | yes | yes |
143| build log                   | yes | yes | yes |
144| build jobs                  | yes | yes | yes |
145| build trigger               | yes | yes | yes |
146| build cancel                | yes | no  | no  |
147| dependency checks on/off    | yes | yes | no  |
148| dependency status           | yes | no  | no  |
149| delete, transfer            | yes | no  | no  |
150| release delete              | yes | yes | no  |
151
152No row is web-only any more. Blame, file editing, log at a ref,
153archive, the public listing and the wiki were all in that state — a
154handler reading git or the store directly instead of dispatching a
155command — until krz/gitbay!99, !101 and !102 gave them commands.
156
157=build cancel= withdraws a queued build, or ends a running one: the
158server closes the runner's log session and the runner kills the step
159within a couple of seconds. Cancelling a duplicate of a commit that
160already passed the job puts that result back on the commit. No button
161on the build page yet.
162
163Dependency checks are off until a repository's admin turns them on: the
164check tells a public registry what the repository depends on. =repo deps
165status= lists what is behind and has no web view because the report
166itself is an issue the worker opens, rewrites and closes, which every
167surface already reads.
168
169The wiki row covers reading. A wiki lives at =.gitbay/wiki/= on the
170default branch, so editing one is editing a file in the repository —
171a push, or =repo commit-file= — and there is no wiki-specific edit row
172to have parity on. The web editor reaches it on any repository that
173permits server-authored commits; one requiring verified signatures
174does not, because the server signs nothing on a user's behalf, so
175those wikis are push-only.
176
177=n/a= marks a capability deliberately absent from a surface rather than
178missing from it. Archive download is =n/a= on iOS: the read API carries
179a command's stdout as a JSON string, so a gzip stream cannot survive it,
180and the app has nowhere useful to put a tarball — the brief rules out
181local git, so there is no clone, checkout or build to feed. The web's
182route stays the way to get one.
183
184A README or wiki page's org renders per surface: the web through
185go-org, the iOS client through the shared OrgSwift package
186(=krz/org-swift=). OrgSwift is held to orgo's output by the
187=krz/org-conformance= corpus — golden renderings from orgo, itself
188diffed against Emacs =ox-html= — so constructs the iOS client used to
189approximate (tables, footnotes, timestamps, heading tags, nested lists)
190now render the way the reference does. go-org is not yet on the corpus.
191
192* Discovery
193
194| capability                       | cli | web | ios |
195|----------------------------------+-----+-----+-----|
196| search repositories              | yes | yes | yes |
197| search issues and merge requests | yes | yes | no  |
198| browse all public repositories   | yes | yes | yes |
199| profile page                     | yes | yes | yes |
200| profile about and links          | yes | yes | no  |
201| activity feed                    | yes | yes | yes |
202| command reference                | yes | no  | n/a |
203
204=explore= is the listing without a query; =repo search= is the one with.
205=search= is both plus the title and body of every issue and merge
206request the caller can read, over FTS5; the web serves it at =/search=
207with a field in the rail, and an anonymous visitor gets the public rows
208from the same query. =issue list --search= and =mr list --search= narrow
209one repository. What someone types is quoted term by term, so an FTS5
210operator — =c++=, =AND=, a lone quote — is a word to match and never a
211syntax error. =repo grep= remains the per-repository file-contents
212search.
213
214About text renders as markdown or org-mode per the =about_format= it
215was stored with. The iOS =Profile= decoder lists its keys explicitly,
216so it ignores =about= and =links= rather than breaking on them.
217
218=help= lists the command registry. Bare it is an index, one line per
219command, sorted. With a prefix (=help mr=) it adds each command's
220argument syntax, which is the only place flags are written down;
221=gitbay <cmd> --help= asks the server for the same thing, and =--json=
222returns ={path, summary, usage}=. No web page renders it, and a native
223client has no use for one (krz/gitbay#57).
224
225* Accounts
226
227| capability                  | cli | web | ios |
228|-----------------------------+-----+-----+-----|
229| SSH keys: list, add, remove | yes | yes | yes |
230| PGP keys: list, add, remove | yes | yes | yes |
231| email add and verify        | yes | yes | yes |
232| dashboard aggregate         | yes | yes | yes |
233| notification inbox          | yes | yes | no  |
234| API token mint              | yes | no  | no  |
235| account export bundle       | yes | no  | no  |
236| profile set                 | yes | no  | no  |
237| request a login link        | n/a | yes | no  |
238
239Notifications land in an inbox row per recipient whether or not the
240instance sends mail, and mail is the second half when SMTP is
241configured. =notifications list= reads it, unread by default;
242=notifications read <id>... | --all= clears it; the dashboard and the
243web rail carry the unread count. =repo watch= adds you to a
244repository's notifications and =repo unwatch= mutes it, and a mute wins
245over owning the repository or having written the thread.
246
247A login link is requested from the login page by username or verified
248address, and arrives by mail: it works once and expires in fifteen
249minutes. The row is =n/a= for the CLI because a terminal with a
250registered key runs =web login=, which mints a link directly and needs
251no mail. It exists because an account with no SSH key had no way into
252the web at all (krz/gitbay#155). The page offers the form only when the
253instance has SMTP configured; there is no separate switch. The response
254never says whether the account exists.
255
256=profile set= carries description, website, about and links. It is not
257=SSHOnly= — nothing about a bio is a credential, and the JSON API runs
258it — but no surface has ever offered a form, so the =no= above is
259missing UI rather than a rule.
260
261* Organizations
262
263| capability                | cli | web | ios |
264|---------------------------+-----+-----+-----|
265| read members and teams    | yes | yes | yes |
266| members add, remove, role | yes | yes | yes |
267| teams create, delete      | yes | yes | yes |
268| team members              | yes | yes | yes |
269| team repo grants          | yes | yes | yes |
270| create, rename, delete    | yes | no  | no  |
271
272* Pagination
273
274=issue list=, =mr list=, =repo list=, and =feed= take =--limit <n>=
275and =--cursor <c>=. Cursors are opaque; each page carries the next
276one. Without the flags a list stays complete, so existing scripts are
277unchanged. The web pages the issue and merge request lists at fifty
278with the same cursors; iOS pages with them too.
279
280* SSH only, by design
281
282Build secrets, mirror configuration and tokens, custom domain claims,
283API token minting, deploy keys, account and instance administration. Deleting or transferring a repository is also
284CLI-only: both want a typed confirmation, not a button.
285
286These are the only rows where a =no= is intended. Everywhere else a
287=no= is work outstanding, and =n/a= means a surface cannot usefully
288carry the capability at all — see the archive note above.