# zfj Zig bindings for the Forgejo API, generated from the API description Forgejo publishes with each release, and a command-line tool built on them. ## Language ### The API description **Specification**: The Swagger 2.0 document a Forgejo release publishes, describing every operation and model of its API. _Avoid_: schema, spec file, OpenAPI document **Tag**: The heading under which the specification files an operation; one operation may carry more than one. _Avoid_: category, group, section ### Connecting **Instance**: One Forgejo server, reached at one base URL. _Avoid_: host, server, forge, site **Default instance**: The instance the tool reaches when nothing names one. _Avoid_: current host, active instance **Client**: A connection to one Forgejo instance: where it is, and the token it is reached with. _Avoid_: session, connection, API client **Tag client**: The operations filed under one tag, reached through a client. An operation with several tags belongs to each of their tag clients. _Avoid_: service, sub-client, API client ### Operations **Operation**: One call the API offers, identified by the specification's `operationId`. _Avoid_: endpoint, method, route, request **Operation name**: An operation's `operationId` with its first letter lowercased, and otherwise exactly as Forgejo wrote it — unless it collides, when it is a name chosen by hand. _Avoid_: function name, method name **Params**: The path, query, header and form values one operation is called with: everything it sends but its request body. _Avoid_: options, arguments, parameters struct **Request body**: The model an operation sends as the body of its request. _Avoid_: payload, body params ### Models **Model**: A type the specification defines and names, carried as a request body or a response. _Avoid_: schema, definition, DTO, struct **Option model**: A model Forgejo named with an `Option` or `Options` suffix, sent as a request body to create or change something. Never the params of an operation. _Avoid_: options, params **Inline model**: A model the specification describes without naming, inside another model; zfj names it after the model and field it appears in. _Avoid_: anonymous type, nested type ### The command-line tool **Plumbing command**: A command that performs exactly one operation, named after it, and prints the response as the API sent it. _Avoid_: raw command, low-level command, API command **Porcelain command**: A command shaped around a task rather than an operation, which may perform several operations to carry it out. _Avoid_: high-level command, friendly command, subcommand **Global option**: An option that governs the tool itself — which instance, what output — rather than the operation or task; written only before the command. _Avoid_: global flag, top-level flag **Completion script**: The short script a shell loads that asks zfj what can come next on its command line. _Avoid_: completion file, completer ### Repositories **Repository**: A repository on an instance, named `/`. _Avoid_: repo, project **Owner**: The user or organization a repository belongs to. _Avoid_: namespace, account **Clone**: A local git copy of a repository, whose remotes say where it came from. _Avoid_: checkout, working copy, local repo **Fork**: A repository created as a copy of another, which Forgejo records as its parent. Never a mirror. _Avoid_: copy, mirror **Unit**: One of the features a repository can turn on or off: issues, wiki, pull requests, projects, releases, packages, Forgejo Actions. _Avoid_: feature, module, section ### Forgejo Actions **Forgejo Actions**: Forgejo's continuous integration feature, as a whole. The name of the feature, never of anything inside it. _Avoid_: actions, CI **Workflow**: A file in a repository's `.forgejo/workflows/` saying what to run and on which events. _Avoid_: pipeline, action **Run**: One execution of a workflow, started by an event or by dispatch, and belonging to one repository. _Avoid_: action run, workflow run, build, pipeline **Run number**: The number a run is given within its repository, counting from 1: the one the web interface shows, and the one by which a person names a run. _Avoid_: run ID, run index **Job**: One of the jobs a run is made of, carried out on a runner. A job can be tried more than once. _Avoid_: task, step **Attempt**: One try at a job, numbered from 1; a job's log is the log of one attempt. _Avoid_: rerun, retry **Action**: A reusable step a workflow uses, such as `actions/checkout`. Never a run, a job or the feature. _Avoid_: plugin ### Issues **Blocker**: An issue that must be closed before another issue can be worked on, recorded as a Forgejo issue dependency. An issue is unblocked when all of its blockers are closed. _Avoid_: dependency, prerequisite, parent