issues

README

issues

Package issues provides an issues service definition.

Installation

go get github.com/shurcooL/issues

Directories

Path	Synopsis
fs	Package fs implements issues.Service using a virtual filesystem.
githubapi	Package githubapi implements issues.Service using GitHub API clients.
maintner	Package maintner implements a read-only issues.Service using a x/build/maintner corpus.

License

• MIT License

Documentation

Overview

Package issues provides an issues service definition.

Index

• type Change
• type Close
• type Comment
  • func (c Comment) Validate() error
• type CommentRequest
  • func (cr CommentRequest) Validate() (requiresEdit bool, err error)
• type Commit
• type CopierFrom
• type Edited
• type Event
• type EventType
  • func (et EventType) Valid() bool
• type Issue
  • func (i Issue) Validate() error
• type IssueListOptions
• type IssueRequest
  • func (ir IssueRequest) Validate() error
• type Label
• type ListOptions
• type Milestone
• type RGB
  • func (c RGB) HexString() string
  • func (c RGB) RGBA() (r, g, b, a uint32)
• type Rename
• type RepoSpec
  • func (rs RepoSpec) String() string
• type Service
• type State
• type StateFilter
• type TimelineLister

Types

type Change

type Change struct {
	State   state.Change
	Title   string
	HTMLURL string
}

Change describes a change that closed an issue.

type Close

type Close struct {
	Closer interface{} // Change, Commit, nil.
}

Close provides details for a Closed event.

type Comment

type Comment struct {
	ID        uint64
	User      users.User
	CreatedAt time.Time
	Edited    *Edited // Edited is nil if the comment hasn't been edited.
	Body      string
	Reactions []reactions.Reaction
	Editable  bool // Editable represents whether the current user (if any) can perform edit operations on this comment (or the encompassing issue).
}

Comment represents a comment left on an issue.

func (Comment) Validate

func (c Comment) Validate() error

Validate returns non-nil error if the comment is invalid.

type CommentRequest

type CommentRequest struct {
	ID       uint64
	Body     *string            // If not nil, set the body.
	Reaction *reactions.EmojiID // If not nil, toggle this reaction.
}

CommentRequest is a request to edit a comment.

func (CommentRequest) Validate

func (cr CommentRequest) Validate() (requiresEdit bool, err error)

Validate validates the comment edit request, returning an non-nil error if it's invalid. requiresEdit reports if the edit request needs edit rights or if it can be done by anyone that can react.

type Commit

type Commit struct {
	SHA             string
	Message         string
	AuthorAvatarURL string
	HTMLURL         string
}

Commit describes a commit that closed an issue.

type CopierFrom

type CopierFrom interface {
	// CopyFrom copies all issues from src for specified repo.
	// ctx should provide permission to access all issues in src.
	CopyFrom(ctx context.Context, src Service, repo RepoSpec) error
}

CopierFrom is an optional interface that allows copying issues between services.

type Edited

type Edited struct {
	By users.User
	At time.Time
}

Edited provides the actor and timing information for an edited item.

type Event

type Event struct {
	ID        uint64
	Actor     users.User
	CreatedAt time.Time
	Type      EventType
	Close     Close      // Close is only specified for Closed events.
	Rename    *Rename    // Rename is only provided for Renamed events.
	Label     *Label     // Label is only provided for Labeled and Unlabeled events.
	Milestone *Milestone // Milestone is only provided for Milestoned and Demilestoned events.
}

Event represents an event that occurred around an issue.

type EventType

type EventType string

EventType is the type of an event.

const (
	// Reopened is when an issue is reopened.
	Reopened EventType = "reopened"
	// Closed is when an issue is closed.
	Closed EventType = "closed"
	// Renamed is when an issue is renamed.
	Renamed EventType = "renamed"
	// Labeled is when an issue is labeled.
	Labeled EventType = "labeled"
	// Unlabeled is when an issue is unlabeled.
	Unlabeled EventType = "unlabeled"
	// Milestoned is when an issue is milestoned.
	Milestoned EventType = "milestoned"
	// Demilestoned is when an issue is demilestoned.
	Demilestoned EventType = "demilestoned"
	// CommentDeleted is when an issue comment is deleted.
	CommentDeleted EventType = "comment_deleted"
)

func (EventType) Valid

func (et EventType) Valid() bool

Valid returns non-nil error if the event type is invalid.

type Issue

type Issue struct {
	ID     uint64
	State  State
	Title  string
	Labels []Label
	Comment
	Replies int // Number of replies to this issue (not counting the mandatory issue description comment).
}

Issue represents an issue on a repository.

func (Issue) Validate

func (i Issue) Validate() error

Validate returns non-nil error if the issue is invalid.

type IssueListOptions

type IssueListOptions struct {
	State StateFilter
}

IssueListOptions are options for list operations.

type IssueRequest

type IssueRequest struct {
	State *State
	Title *string
}

IssueRequest is a request to edit an issue. To edit the body, use EditComment with comment ID 0.

func (IssueRequest) Validate

func (ir IssueRequest) Validate() error

Validate returns non-nil error if the issue request is invalid.

type Label

type Label struct {
	Name  string
	Color RGB
}

Label represents a label.

type ListOptions

type ListOptions struct {
	// Start is the index of first result to retrieve, zero-indexed.
	Start int

	// Length is the number of results to include.
	Length int
}

ListOptions controls pagination.

type Milestone

type Milestone struct {
	Name string
}

Milestone represents a milestone.

type RGB

type RGB struct {
	R, G, B uint8
}

TODO: Dedup.

RGB represents a 24-bit color without alpha channel.

func (RGB) HexString

func (c RGB) HexString() string

HexString returns a hexadecimal color string. For example, "#ff0000" for red.

func (RGB) RGBA

func (c RGB) RGBA() (r, g, b, a uint32)

type Rename

type Rename struct {
	From string
	To   string
}

Rename provides details for a Renamed event.

type RepoSpec

type RepoSpec struct {
	URI string // URI is clean '/'-separated URI. E.g., "example.com/user/repo".
}

RepoSpec is a specification for a repository.

func (RepoSpec) String

func (rs RepoSpec) String() string

String implements fmt.Stringer.

type Service

type Service interface {
	// List issues.
	List(ctx context.Context, repo RepoSpec, opt IssueListOptions) ([]Issue, error)
	// Count issues.
	Count(ctx context.Context, repo RepoSpec, opt IssueListOptions) (uint64, error)

	// Get an issue.
	Get(ctx context.Context, repo RepoSpec, id uint64) (Issue, error)

	// ListComments lists comments for specified issue id.
	ListComments(ctx context.Context, repo RepoSpec, id uint64, opt *ListOptions) ([]Comment, error)
	// ListEvents lists events for specified issue id.
	ListEvents(ctx context.Context, repo RepoSpec, id uint64, opt *ListOptions) ([]Event, error)

	// Create a new issue.
	Create(ctx context.Context, repo RepoSpec, issue Issue) (Issue, error)
	// CreateComment creates a new comment for specified issue id.
	CreateComment(ctx context.Context, repo RepoSpec, id uint64, comment Comment) (Comment, error)

	// Edit the specified issue id.
	Edit(ctx context.Context, repo RepoSpec, id uint64, ir IssueRequest) (Issue, []Event, error)
	// EditComment edits comment of specified issue id.
	EditComment(ctx context.Context, repo RepoSpec, id uint64, cr CommentRequest) (Comment, error)
}

Service defines methods of an issue tracking service.

type State

type State string

State represents the issue state.

const (
	// OpenState is when an issue is open.
	OpenState State = "open"
	// ClosedState is when an issue is closed.
	ClosedState State = "closed"
)

type StateFilter

type StateFilter State

StateFilter is a filter by state.

const (
	// AllStates is a state filter that includes all issues.
	AllStates StateFilter = "all"
)

type TimelineLister

type TimelineLister interface {
	// IsTimelineLister reports whether the underlying service implements TimelineLister
	// fully for the specified repo.
	IsTimelineLister(repo RepoSpec) bool

	// ListTimeline lists timeline items (Comment, Event) for specified issue id
	// in chronological order, if IsTimelineLister(repo) reported positively.
	// The issue description comes first in a timeline.
	ListTimeline(ctx context.Context, repo RepoSpec, id uint64, opt *ListOptions) ([]interface{}, error)
}

TimelineLister is an optional interface that combines ListComments and ListEvents methods into one that includes both. It's available for situations where this is more efficient to implement.