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 <owner>/<repo>.
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