forge

Documentation

Overview

Package forge provides an abstraction layer between git-spice and the underlying forge (e.g. GitHub, GitLab, Bitbucket).

Index

• Variables
• func Register(f Forge) (unregister func())
• type ChangeID
• type ChangeMetadata
• type ChangeState
  • func (s ChangeState) MarshalText() ([]byte, error)
  • func (s ChangeState) String() string
  • func (s *ChangeState) UnmarshalText(b []byte) error
• type ChangeTemplate
• type EditChangeOptions
• type FindChangeItem
• type FindChangesOptions
• type Forge
  • func Lookup(id string) (Forge, bool)
  • func MatchForgeURL(remoteURL string) (forge Forge, ok bool)
• type Repository
  • func OpenRepositoryURL(ctx context.Context, remoteURL string) (repo Repository, _ error)
• type SubmitChangeRequest
• type SubmitChangeResult

Variables

var ErrUnsupportedURL = errors.New("unsupported URL")

ErrUnsupportedURL indicates that the given remote URL does not match any registered forge.

Functions

func Register

func Register(f Forge) (unregister func())

Register registers a forge with the given ID. Returns a function to unregister the forge.

Types

type ChangeID

type ChangeID interface {
	String() string
}

ChangeID is a unique identifier for a change in a repository.

type ChangeMetadata

type ChangeMetadata interface {
	ForgeID() string

	// ChangeID is a human-readable identifier for the change.
	// This is presented to the user in the UI.
	ChangeID() ChangeID
}

ChangeMetadata defines Forge-specific per-change metadata. This metadata is persisted to the state store alongside the branch state. It is used to track the relationship between a branch and its corresponding change in the forge.

The implementation is per-forge, and should contain enough information for the forge to uniquely identify a change within a repository.

The metadata must be JSON-serializable (as defined by methods on Forge).

type ChangeState

type ChangeState int

ChangeState is the current state of a change.

const (
	// ChangeOpen specifies that a change is open.
	ChangeOpen ChangeState = iota + 1

	// ChangeMerged specifies that a change has been merged.
	ChangeMerged

	// ChangeClosed specifies that a change has been closed.
	ChangeClosed
)

func (ChangeState) MarshalText

func (s ChangeState) MarshalText() ([]byte, error)

MarshalText serialize the change state to text. This implements encoding.TextMarshaler.

func (ChangeState) String

func (s ChangeState) String() string

func (*ChangeState) UnmarshalText

func (s *ChangeState) UnmarshalText(b []byte) error

UnmarshalText parses the change state from text. This implements encoding.TextUnmarshaler.

type ChangeTemplate

type ChangeTemplate struct {
	// Filename is the name of the template file.
	//
	// This is NOT a path.
	Filename string

	// Body is the content of the template file.
	Body string
}

ChangeTemplate is a template for a new change proposal.

type EditChangeOptions

type EditChangeOptions struct {
	// Base specifies the name of the base branch.
	//
	// If unset, the base branch is not changed.
	Base string

	// Draft specifies whether the change should be marked as a draft.
	// If unset, the draft status is not changed.
	Draft *bool
}

EditChangeOptions specifies options for an operation to edit an existing change.

type FindChangeItem

type FindChangeItem struct {
	// ID is a unique identifier for the change.
	ID ChangeID

	// URL is the web URL at which the change can be viewed.
	URL string

	// State is the current state of the change.
	State ChangeState

	// Subject is the title of the change.
	Subject string

	// HeadHash is the hash of the commit at the top of the change.
	HeadHash git.Hash

	// BaseName is the name of the base branch
	// that this change is proposed against.
	BaseName string

	// Draft is true if the change is not yet ready to be reviewed.
	Draft bool
}

FindChangeItem is a single result from searching for changes in the repository.

type FindChangesOptions

type FindChangesOptions struct {
	State ChangeState // 0 = all

	// Limit specifies the maximum number of changes to return.
	// Changes are sorted by most recently updated.
	// Defaults to 10.
	Limit int
}

FindChangesOptions specifies filtering options for searching for changes.

type Forge

type Forge interface {
	// ID reports a unique identifier for the forge, e.g. "github".
	ID() string

	// MatchURL reports whether the given remote URL is hosted on the forge.
	MatchURL(remoteURL string) bool

	// OpenURL opens a repository hosted on the forge
	// with the given remote URL.
	//
	// This will only be called if MatchURL reports true.
	OpenURL(ctx context.Context, remoteURL string) (Repository, error)

	// ChangeTemplatePaths reports the case-insensitive paths at which
	// it's possible to define change templates in the repository.
	ChangeTemplatePaths() []string

	// MarshalChangeMetadata serializes the given change metadata
	// into a valid JSON blob.
	MarshalChangeMetadata(ChangeMetadata) (json.RawMessage, error)

	// UnmarshalChangeMetadata deserializes the given JSON blob
	// into change metadata.
	UnmarshalChangeMetadata(json.RawMessage) (ChangeMetadata, error)
}

Forge is a forge that hosts Git repositories.

func Lookup

func Lookup(id string) (Forge, bool)

Lookup looks up a registered forge by its ID.

func MatchForgeURL

func MatchForgeURL(remoteURL string) (forge Forge, ok bool)

MatchForgeURL attempts to match the given remote URL with a registered forge. Returns the matched forge and true if a match was found.

type Repository

type Repository interface {
	Forge() Forge

	SubmitChange(ctx context.Context, req SubmitChangeRequest) (SubmitChangeResult, error)
	EditChange(ctx context.Context, id ChangeID, opts EditChangeOptions) error
	FindChangesByBranch(ctx context.Context, branch string, opts FindChangesOptions) ([]*FindChangeItem, error)
	FindChangeByID(ctx context.Context, id ChangeID) (*FindChangeItem, error)
	ChangeIsMerged(ctx context.Context, id ChangeID) (bool, error)

	// NewChangeMetadata builds a ChangeMetadata for the given change ID.
	//
	// This may perform network requests to fetch additional information
	// if necessary.
	NewChangeMetadata(ctx context.Context, id ChangeID) (ChangeMetadata, error)

	// ListChangeTemplates returns templates defined in the repository
	// for new change proposals.
	//
	// Returns an empty list if no templates are found.
	ListChangeTemplates(context.Context) ([]*ChangeTemplate, error)
}

Repository is a Git repository hosted on a forge.

func OpenRepositoryURL

func OpenRepositoryURL(ctx context.Context, remoteURL string) (repo Repository, _ error)

OpenRepositoryURL opens a repository hosted on a forge by parsing the given remote URL.

It will attempt to match the URL with all registered forges.

type SubmitChangeRequest

type SubmitChangeRequest struct {
	// Subject is the title of the change.
	Subject string // required

	// Body is the description of the change.
	Body string

	// Base is the name of the base branch
	// that this change is proposed against.
	Base string // required

	// Head is the name of the branch containing the change.
	//
	// This must have already been pushed to the remote.
	Head string // required

	// Draft specifies whether the change should be marked as a draft.
	Draft bool
}

SubmitChangeRequest is a request to submit a new change in a repository. The change must have already been pushed to the remote.

type SubmitChangeResult

type SubmitChangeResult struct {
	ID  ChangeID
	URL string
}

SubmitChangeResult is the result of creating a new change in a repository.