godash

Documentation

Overview

Package godash generates dashboards about issues and CLs in the Go Github and Gerrit projects. There is a user-friendly interface in the godash command-line tool at golang.org/x/build/cmd/godash

Index

• func NewGitHubClient(project, authToken string, transport http.RoundTripper) *github.Client
• func PrintHTML(w io.Writer, data string)
• type CL
  • func ParseCL(ci *gerrit.ChangeInfo, reviewers *Reviewers, goReleaseCycle int) *CL
  • func (cl *CL) Age(now time.Time) time.Duration
  • func (cl *CL) Delay(now time.Time) time.Duration
  • func (cl *CL) Dirs() []string
  • func (cl *CL) Summary(now time.Time) string
• type Data
  • func (d *Data) FetchData(ctx context.Context, gh *github.Client, ger *gerrit.Client, ...) error
  • func (d *Data) GetActiveMilestones() []string
  • func (d *Data) GroupData(includeIssues, allCLs bool) []*Group
  • func (d *Data) PrintCLs(w io.Writer)
  • func (d *Data) PrintIssues(w io.Writer)
• type Group
• type Issue
• type IssueStat
• type Item
  • func (item *Item) Dir() string
• type MilestoneChange
• type Reviewers
  • func (r *Reviewers) GobDecode(b []byte) error
  • func (r *Reviewers) GobEncode() ([]byte, error)
  • func (r *Reviewers) IsReviewer(addr string) bool
  • func (r *Reviewers) LoadGithub(client *github.Client) error
  • func (r *Reviewers) LoadLocal()
  • func (r *Reviewers) MarshalJSON() ([]byte, error)
  • func (r *Reviewers) Preferred(addr string) string
  • func (r *Reviewers) Resolve(short string) string
  • func (r *Reviewers) ResolveGitHub(login string) string
  • func (r *Reviewers) Shorten(addr string) string
  • func (r *Reviewers) UnmarshalJSON(b []byte) error
• type Stats
  • func (s *Stats) Update(ctx context.Context, gh *github.Client, log func(string, ...interface{})) error
  • func (s *Stats) UpdateIssue(gh *github.Client, num int, log func(string, ...interface{})) error

Functions

func NewGitHubClient

func NewGitHubClient(project, authToken string, transport http.RoundTripper) *github.Client

func PrintHTML

func PrintHTML(w io.Writer, data string)

PrintHTML converts the text output of PrintIssues or PrintCLs into an HTML page.

Types

type CL

type CL struct {
	Number             int            // CL number
	Subject            string         // subject (first line of commit message)
	Project            string         // "go" or a subrepository name
	Author             string         // author, short form or else full email
	AuthorEmail        string         // author, full email
	Reviewer           string         // expected reviewer, short form or else full email
	ReviewerEmail      string         // expected reviewer, full email
	Start              time.Time      // time CL was first uploaded
	NeedsReview        bool           // CL is waiting for reviewer (otherwise author)
	NeedsReviewChanged time.Time      // time NeedsReview last changed
	Closed             bool           // CL closed with R=close
	DoNotReview        bool           // CL marked DO NOT REVIEW
	Issues             []int          // issues referenced by commit message
	Scores             map[string]int // current review scores
	Files              []string       // files changed in CL
	Status             string         // "new", "submitted", "merged", ...
}

CL records information about a single CL. This is also used by golang.org/x/build/cmd/cl and any changes need to reflected in its doc comment.

func ParseCL

func ParseCL(ci *gerrit.ChangeInfo, reviewers *Reviewers, goReleaseCycle int) *CL

ParseCL takes a ChangeInfo as returned from the Gerrit API and applies Go-project-specific logic to turn it into a CL struct. The primary information that is added is the CL's state in the Go review process, based on parsing R= lines in the comments and the most recent commit message of the CL.

func (*CL) Age

func (cl *CL) Age(now time.Time) time.Duration

func (*CL) Delay

func (cl *CL) Delay(now time.Time) time.Duration

func (*CL) Dirs

func (cl *CL) Dirs() []string

Dirs returns the list of directories that this CL might be said to be about, in preference order.

func (*CL) Summary

func (cl *CL) Summary(now time.Time) string

type Data

type Data struct {
	Issues     map[int]*Issue
	CLs        []*CL
	Milestones []*github.Milestone
	// GoReleaseCycle is the minor version of the current
	// under-development Go release. Issues and CLs for versions
	// greater than the current Go release will be hidden.
	GoReleaseCycle int
	Now            time.Time

	Reviewers *Reviewers
}

Data represents all the data needed to compute the dashboard

func (*Data) FetchData

func (d *Data) FetchData(ctx context.Context, gh *github.Client, ger *gerrit.Client, log func(string, ...interface{}), days int, clOnly, includeMerged bool) error

func (*Data) GetActiveMilestones

func (d *Data) GetActiveMilestones() []string

func (*Data) GroupData

func (d *Data) GroupData(includeIssues, allCLs bool) []*Group

GroupData returns information about all the issues and CLs, grouping related issues and CLs together and then grouping those items by directory affected. includeIssues specifies whether to include both CLs and issues or just CLs. allCLs specifies whether to include CLs from non-go projects (i.e. x/ repos).

func (*Data) PrintCLs

func (d *Data) PrintCLs(w io.Writer)

func (*Data) PrintIssues

func (d *Data) PrintIssues(w io.Writer)

type Group

type Group struct {
	Dir   string
	Items []*Item
}

type Issue

type Issue struct {
	Number                   int
	Title                    string
	Labels                   []string
	Reporter                 string
	Assignee                 string
	Milestone                string
	State                    string
	Created, Updated, Closed time.Time
}

type IssueStat

type IssueStat struct {
	Created, Closed, Updated time.Time
	// Milestone contains the milestone the issue is currently
	// associated with.
	Milestone string
	// MilestoneHistory contains previous milestones and the time
	// the issue ceased to be assigned to that milestone. We store
	// this so the slice can be empty for most issues that have
	// only ever been associated with one milestone.
	MilestoneHistory []MilestoneChange
}

IssueStat holds an individual issue's important facts.

type Item

type Item struct {
	Issue *Issue
	CLs   []*CL
}

func (*Item) Dir

func (item *Item) Dir() string

type MilestoneChange

type MilestoneChange struct {
	// Name is the name of the milestone.
	Name string
	// Until is the time that the milestone was removed.
	Until time.Time
}

MilestoneChange stores a historical milestone. We store historical milestones separately since most issues have only ever had one milestone; we can save on constructing and serializing the slice then.

type Reviewers

type Reviewers struct {
	// contains filtered or unexported fields
}

Reviewers tracks the popularity of reviewers in a Git repository. It can be used to resolve e-mail addresses into short names and vice versa.

func (*Reviewers) GobDecode

func (r *Reviewers) GobDecode(b []byte) error

func (*Reviewers) GobEncode

func (r *Reviewers) GobEncode() ([]byte, error)

func (*Reviewers) IsReviewer

func (r *Reviewers) IsReviewer(addr string) bool

IsReviewer reports whether the provided address is a known reviewer.

func (*Reviewers) LoadGithub

func (r *Reviewers) LoadGithub(client *github.Client) error

LoadGithub fetches the list of reviewers for the current repository, sorted by how many reviews each has done.

func (*Reviewers) LoadLocal

func (r *Reviewers) LoadLocal()

func (*Reviewers) MarshalJSON

func (r *Reviewers) MarshalJSON() ([]byte, error)

func (*Reviewers) Preferred

func (r *Reviewers) Preferred(addr string) string

Preferred takes an address and returns the preferred e-mail address for that user, which may be the same. It does this by resolving the GitHub username and then returning the address most-used for commits on that username.

func (*Reviewers) Resolve

func (r *Reviewers) Resolve(short string) string

Resolve takes a short username and returns the matching full e-mail address, or "" if the username could not be resolved.

func (*Reviewers) ResolveGitHub

func (r *Reviewers) ResolveGitHub(login string) string

ResolveGitHub takes a GitHub login name and returns the matching full e-mail address, or "" if the name could not be resolved.

func (*Reviewers) Shorten

func (r *Reviewers) Shorten(addr string) string

Shorten will potentially shorten a full e-mail address if the short version maps back to that full address.

func (*Reviewers) UnmarshalJSON

func (r *Reviewers) UnmarshalJSON(b []byte) error

type Stats

type Stats struct {
	// Issues is a map of issue number to per-issue data.
	Issues map[int]*IssueStat
	// Since is the high watermark for issue update times; any
	// issues updated since Since will be refetched.
	Since time.Time
	// IssueDetailSince is the high watermark for issue details;
	// this is separate because requesting issue details uses up
	// quota, and we cannot request all issues at once.
	IssueDetailSince time.Time
}

Stats contains information about all GitHub issues.

We track statistics for each issue to produce graphs:

• Issue creation time
• TODO(quentin): First reply time from Go team member
• Issue close time
• Issue current milestone
• History of issue labels + milestones

As well as the following global info

• Last issue update time
• Last issue detail update time

func (*Stats) Update

func (s *Stats) Update(ctx context.Context, gh *github.Client, log func(string, ...interface{})) error

Update fetches new information from GitHub for any issues modified since s was last updated.

func (*Stats) UpdateIssue

func (s *Stats) UpdateIssue(gh *github.Client, num int, log func(string, ...interface{})) error

UpdateIssue updates a single issue, without moving s.Since.