Module forge

Uniform access to github and gitlab

Currently, listing and creating merge requests is suppored.

Start by creating a Forge, probably by initialising a Config with default-based a literal and calling Setup::forge.

Terminology and model

• Repository. A single git tree that can contain code, and has other things associated with it such as issues and merge requests. (GitHub, GitLab: project.)

  Identified in the gitforge API by a string, which is typically the path suffix.

• Merge Request. A request to incorporate changes from a source repository and branch into a target repository and branch. Forges typically associate merge requsts primarily with the target repository. A merge request typically has an associated discussion.

  (GitHub: a pull request.)

• Issue. A feature request or bug report, associated with a repository, and an associated discussion. *Not currently supported by this library.

• Merge request or issue Number. A (usually short) string which uniquely identifies a merge request or issue within a repository.

• User. An individual user, or possibly, organisation. Represented as a string, being the username (as used, eg, as a slug in the forge’s URLs).

• Branch. A git branch (on the server), ie a remote ref named refs/heads/BRANCH. Identified by the string BRANCH.

See the individual forge module docs for the mapping.

Non-exhaustive structs

Some structs in this api have fields named _non_exhaustive. This indicates that the struct may be extended with additional fields in future, and that this won’t be considered a semver breaking change.

Do not explicitly initialise such a field. Instead, use .. syntax to initialise all the fields you are not naming. Typically, you would write ..Default::default().

This rule is in addition to some (other) structs being marked #[non_exhaustive].

Non-exhaustive enums

Some enums have variants named _NonExhaustive. This indicates that the enum may be extended with additional variants in future, and that this won’t be considered a semver breaking change.

Do not construct such an enum variant. The library will panic if it finds one.

This rule is in addition to some (other) enums being marked #[non_exhaustive].

Structs

Config

Instructions for how to connect to a forge

IssueMrState

Overall state of an Issue or Merge Request

RepoBranch

Repository and branch

Req_CreateMergeRequest

Create a new merge request.

Req_MergeRequests

Search for merge requests.

Resp_MergeRequest

Merge request, in a response

Token

Secret access token.

Enums

Error

Errors accessing forges

IssueMrLocked

Whether an Issue or Merge Request is locked

IssueMrStatus

Issue or Merge Request status

Kind

What protocol to use to access a forge. Don’t hardcode.

RemoteObjectKind

Kind of a thing on a forge. Used mostly in errors.

Req

Request (command) to a forge

Resp

Response from a forge

TokenConfig

Instructions for how to obtain an access token

Traits

Forge

Main trait; forge objects are Box<dyn Forge>

ForgeMethods

Main entrypoints once a Forge has been constructed.