README

Go Reference

golang.org/x/build/maintner

Package maintner mirrors, searches, syncs, and serves Git, Github, and Gerrit metadata.

Expand ▾ Collapse ▴

Documentation

Overview

    Package maintner mirrors, searches, syncs, and serves Git, Github, and Gerrit metadata.

    Maintner is short for "Maintainer". This package is intended for use by many tools. The name of the daemon that serves the maintner data to other tools is "maintnerd".

    Example

    Code:

    package main
    
    import (
    	"context"
    	"fmt"
    	"log"
    	"os"
    	"path/filepath"
    
    	"golang.org/x/build/maintner"
    )
    
    func main() {
    	cacheDir := filepath.Join(os.Getenv("HOME"), "var", "maintnerd")
    	// maintner.golang.org contains the metadata for the Go project and related
    	// Github repositories and issues.
    	mutSrc := maintner.NewNetworkMutationSource("https://maintner.golang.org/logs", cacheDir)
    	corpus := new(maintner.Corpus)
    	if err := corpus.Initialize(context.Background(), mutSrc); err != nil {
    		log.Fatal(err)
    	}
    	err := corpus.GitHub().ForeachRepo(func(r *maintner.GitHubRepo) error {
    		fmt.Println(r.ID())
    		return nil
    	})
    	if err != nil {
    		log.Fatal(err)
    	}
    }
    
    Example (FromDisk)

    Code:

    package main
    
    import (
    	"context"
    	"fmt"
    	"log"
    	"os"
    	"path/filepath"
    
    	"golang.org/x/build/maintner"
    )
    
    func main() {
    	logger := maintner.NewDiskMutationLogger(filepath.Join(os.Getenv("HOME"), "var", "maintnerd"))
    	corpus := new(maintner.Corpus)
    	corpus.Initialize(context.Background(), logger)
    	err := corpus.GitHub().ForeachRepo(func(r *maintner.GitHubRepo) error {
    		fmt.Println(r.ID())
    		return nil
    	})
    	if err != nil {
    		log.Fatal(err)
    	}
    }
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var ErrSplit = errors.New("maintner: leader server's history split, process out of sync")

      ErrSplit is returned when the the client notices the leader's mutation log has changed. This can happen if the leader restarts with uncommitted transactions. (The leader only commits mutations periodically.)

      Functions

      func TailNetworkMutationSource

      func TailNetworkMutationSource(ctx context.Context, server string, fn func(MutationStreamEvent) error) error

        TailNetworkMutationSource calls fn for all new mutations added to the log on server. Events with the End field set to true are not sent, so all events will have exactly one of Mutation or Err fields set to a non-zero value. It ignores prior events. If the server is restarted and its history diverges, TailNetworkMutationSource may return duplicate events. This therefore does not return a MutationSource, so it can't be accidentally misused for important things. TailNetworkMutationSource returns if fn returns an error, or if ctx expires.

        Types

        type Corpus

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

          Corpus holds all of a project's metadata.

          Many public accessor methods are missing. File bugs at golang.org/issues/new.

          func (*Corpus) Check

          func (c *Corpus) Check() error

            Check verifies the internal structure of the Corpus data structures. It is intended for tests and debugging.

            func (*Corpus) EnableLeaderMode

            func (c *Corpus) EnableLeaderMode(logger MutationLogger, scratchDir string)

              EnableLeaderMode prepares c to be the leader. This should only be called by the maintnerd process.

              The provided scratchDir will store git checkouts.

              func (*Corpus) Gerrit

              func (c *Corpus) Gerrit() *Gerrit

                Gerrit returns the corpus's Gerrit data.

                func (*Corpus) GitCommit

                func (c *Corpus) GitCommit(hash string) *GitCommit

                  GitCommit returns the provided git commit, or nil if it's unknown.

                  func (*Corpus) GitHub

                  func (c *Corpus) GitHub() *GitHub

                    GitHub returns the corpus's github data.

                    func (*Corpus) Initialize

                    func (c *Corpus) Initialize(ctx context.Context, src MutationSource) error

                      Initialize populates the Corpus using the data from the MutationSource. It returns once it's up-to-date. To incrementally update it later, use the Update method.

                      func (*Corpus) RLock

                      func (c *Corpus) RLock()

                        RLock grabs the corpus's read lock. Grabbing the read lock prevents any concurrent writes from mutating the corpus. This is only necessary if the application is querying the corpus and calling its Update method concurrently.

                        func (*Corpus) RUnlock

                        func (c *Corpus) RUnlock()

                          RUnlock unlocks the corpus's read lock.

                          func (*Corpus) SetDebug

                          func (c *Corpus) SetDebug()

                          func (*Corpus) SetGitHubLimiter

                          func (c *Corpus) SetGitHubLimiter(l *rate.Limiter)

                            GitHubLimiter sets a limiter that controls the rate of requests made to GitHub APIs. If nil, requests are not limited. Only valid in leader mode. The limiter must only be set before Sync or SyncLoop is called.

                            func (*Corpus) SetVerbose

                            func (c *Corpus) SetVerbose(v bool)

                              SetVerbose enables or disables verbose logging.

                              func (*Corpus) StartPubSubHelperSubscribe

                              func (c *Corpus) StartPubSubHelperSubscribe(urlBase string)

                                StartPubSubHelperSubscribe starts subscribing to a golang.org/x/build/cmd/pubsubhelper server, such as https://pubsubhelper.golang.org

                                func (*Corpus) Sync

                                func (c *Corpus) Sync(ctx context.Context) error

                                  Sync updates the corpus from its tracked sources.

                                  func (*Corpus) SyncLoop

                                  func (c *Corpus) SyncLoop(ctx context.Context) error

                                    SyncLoop runs forever (until an error or context expiration) and updates the corpus as the tracked sources change.

                                    func (*Corpus) TrackGerrit

                                    func (c *Corpus) TrackGerrit(gerritProj string)

                                      TrackGerrit registers the Gerrit project with the given project as a project to watch and append to the mutation log. Only valid in leader mode. The provided string should be of the form "hostname/project", without a scheme or trailing slash.

                                      func (*Corpus) TrackGitHub

                                      func (c *Corpus) TrackGitHub(owner, repo, token string)

                                        TrackGitHub registers the named GitHub repo as a repo to watch and append to the mutation log. Only valid in leader mode. The token is the auth token to use to make API calls.

                                        func (*Corpus) TrackGoGitRepo

                                        func (c *Corpus) TrackGoGitRepo(goRepo, dir string)

                                          TrackGoGitRepo registers a git directory to have its metadata slurped into the corpus. The goRepo is a name like "go" or "net". The dir is a path on disk.

                                          func (*Corpus) Update

                                          func (c *Corpus) Update(ctx context.Context) error

                                            Update incrementally updates the corpus from its current state to the latest state from the MutationSource passed earlier to Initialize. It does not return until there's either a new change or the context expires. If Update returns ErrSplit, the corpus can longer be updated.

                                            Update must not be called concurrently with any other Update calls. If reading the corpus concurrently while the corpus is updating, you must hold the read lock using Corpus.RLock.

                                            func (*Corpus) UpdateWithLocker

                                            func (c *Corpus) UpdateWithLocker(ctx context.Context, lk sync.Locker) error

                                              UpdateWithLocker behaves just like Update, but holds lk when processing mutation events.

                                              type DiskMutationLogger

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

                                                DiskMutationLogger logs mutations to disk.

                                                Example

                                                Code:

                                                package main
                                                
                                                import (
                                                	"context"
                                                	"fmt"
                                                	"log"
                                                	"os"
                                                	"path/filepath"
                                                
                                                	"golang.org/x/build/maintner"
                                                )
                                                
                                                func main() {
                                                	logger := maintner.NewDiskMutationLogger(filepath.Join(os.Getenv("HOME"), "var", "maintnerd"))
                                                	corpus := new(maintner.Corpus)
                                                	corpus.Initialize(context.Background(), logger)
                                                	err := corpus.GitHub().ForeachRepo(func(r *maintner.GitHubRepo) error {
                                                		fmt.Println(r.ID())
                                                		return nil
                                                	})
                                                	if err != nil {
                                                		log.Fatal(err)
                                                	}
                                                }
                                                

                                                func NewDiskMutationLogger

                                                func NewDiskMutationLogger(directory string) *DiskMutationLogger

                                                  NewDiskMutationLogger creates a new DiskMutationLogger, which will create mutations in the given directory.

                                                  func (*DiskMutationLogger) ForeachFile

                                                  func (d *DiskMutationLogger) ForeachFile(fn func(fullPath string, fi os.FileInfo) error) error

                                                  func (*DiskMutationLogger) GetMutations

                                                  func (d *DiskMutationLogger) GetMutations(ctx context.Context) <-chan MutationStreamEvent

                                                  func (*DiskMutationLogger) Log

                                                    Log will write m to disk. If a mutation file does not exist for the current day, it will be created.

                                                    type Gerrit

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

                                                      Gerrit holds information about a number of Gerrit projects.

                                                      func (*Gerrit) ForeachProjectUnsorted

                                                      func (g *Gerrit) ForeachProjectUnsorted(fn func(*GerritProject) error) error

                                                        ForeachProjectUnsorted calls fn for each known Gerrit project. Iteration ends if fn returns a non-nil value.

                                                        func (*Gerrit) Project

                                                        func (g *Gerrit) Project(server, project string) *GerritProject

                                                          Project returns the specified Gerrit project if it's known, otherwise it returns nil. Server is the Gerrit server's hostname, such as "go.googlesource.com".

                                                          type GerritCL

                                                          type GerritCL struct {
                                                          	// Project is the project this CL is part of.
                                                          	Project *GerritProject
                                                          
                                                          	// Number is the CL number on the Gerrit server (e.g. 1, 2, 3). Gerrit CL
                                                          	// numbers are sparse (CL N does not guarantee that CL N-1 exists) and
                                                          	// Gerrit issues CL's out of order - it may issue CL N, then CL (N - 18),
                                                          	// then CL (N - 40).
                                                          	Number int32
                                                          
                                                          	// Created is the CL creation time.
                                                          	Created time.Time
                                                          
                                                          	// Version is the number of versions of the patchset for this
                                                          	// CL seen so far. It starts at 1.
                                                          	Version int32
                                                          
                                                          	// Commit is the git commit of the latest version of this CL.
                                                          	// Previous versions are available via CommitAtVersion.
                                                          	// Commit is always non-nil.
                                                          	Commit *GitCommit
                                                          
                                                          	// Meta is the head of the most recent Gerrit "meta" commit
                                                          	// for this CL. This is guaranteed to be a linear history
                                                          	// back to a CL-specific root commit for this meta branch.
                                                          	// Meta will always be non-nil.
                                                          	Meta *GerritMeta
                                                          
                                                          	// Metas contains the history of Meta commits, from the oldest (root)
                                                          	// to the most recent. The last item in the slice is the same
                                                          	// value as the GerritCL.Meta field.
                                                          	// The Metas slice will always contain at least 1 element.
                                                          	Metas []*GerritMeta
                                                          
                                                          	// Status will be "merged", "abandoned", "new", or "draft".
                                                          	Status string
                                                          
                                                          	// Private indicates whether this is a private CL.
                                                          	// Empirically, it seems that one meta commit of private CLs is
                                                          	// sometimes visible to everybody, even when the rest of the details
                                                          	// and later meta commits are not. In general, if you see this
                                                          	// being set to true, treat this CL as if it doesn't exist.
                                                          	Private bool
                                                          
                                                          	// GitHubIssueRefs are parsed references to GitHub issues.
                                                          	// Multiple references to the same issue are deduplicated.
                                                          	GitHubIssueRefs []GitHubIssueRef
                                                          
                                                          	// Messages contains all of the messages for this CL, in sorted order.
                                                          	Messages []*GerritMessage
                                                          	// contains filtered or unexported fields
                                                          }

                                                            A GerritCL represents a single change in Gerrit.

                                                            func (*GerritCL) Branch

                                                            func (cl *GerritCL) Branch() string

                                                              Branch returns the CL's branch, with any "refs/heads/" prefix removed.

                                                              func (*GerritCL) ChangeID

                                                              func (cl *GerritCL) ChangeID() string

                                                                ChangeID returns the Gerrit "Change-Id: Ixxxx" line's Ixxxx value from the cl.Msg, if any.

                                                                func (*GerritCL) CommitAtVersion

                                                                func (cl *GerritCL) CommitAtVersion(version int32) *GitCommit

                                                                  CommitAtVersion returns the git commit of the specifid version of this CL. It returns nil if version is not in the range [1, cl.Version].

                                                                  func (*GerritCL) Footer

                                                                  func (cl *GerritCL) Footer(key string) string

                                                                    Footer returns the value of a line of the form <key>: value from the CL’s commit message. The key is case-sensitive and must end in a colon. An empty string is returned if there is no value for key.

                                                                    func (*GerritCL) Owner

                                                                    func (cl *GerritCL) Owner() *GitPerson

                                                                      Owner returns the author of the first commit to the CL. It returns nil on error.

                                                                      func (*GerritCL) OwnerID

                                                                      func (cl *GerritCL) OwnerID() int

                                                                        OwnerID returns the ID of the CL’s owner. It will return -1 on error.

                                                                        func (*GerritCL) References

                                                                        func (cl *GerritCL) References(ref GitHubIssueRef) bool

                                                                          References reports whether cl includes a commit message reference to the provided Github issue ref.

                                                                          func (*GerritCL) Subject

                                                                          func (cl *GerritCL) Subject() string

                                                                            Subject returns the subject of the latest commit message. The subject is separated from the body by a blank line.

                                                                            func (*GerritCL) WorkInProgress

                                                                            func (cl *GerritCL) WorkInProgress() bool

                                                                              WorkInProgress reports whether the CL has its Work-in-progress bit set, per https://gerrit-review.googlesource.com/Documentation/intro-user.html#wip

                                                                              type GerritHashtags

                                                                              type GerritHashtags string

                                                                                GerritHashtags represents a set of "hashtags" on a Gerrit CL.

                                                                                The representation is a comma-separated string, to match Gerrit's internal representation in the meta commits. To support both forms of Gerrit's internal representation, whitespace is optional around the commas.

                                                                                func (GerritHashtags) Contains

                                                                                func (s GerritHashtags) Contains(t string) bool

                                                                                  Contains reports whether the hashtag t is in the set of tags s.

                                                                                  func (GerritHashtags) Foreach

                                                                                  func (s GerritHashtags) Foreach(fn func(string))

                                                                                    Foreach calls fn for each tag in the set s.

                                                                                    func (GerritHashtags) Len

                                                                                    func (s GerritHashtags) Len() int

                                                                                      Len returns the number of tags in the set s.

                                                                                      func (GerritHashtags) Match

                                                                                      func (s GerritHashtags) Match(fn func(string) bool) bool

                                                                                        Match reports whether fn returns true for any tag in the set s. If fn returns true, iteration stops and Match returns true.

                                                                                        type GerritMessage

                                                                                        type GerritMessage struct {
                                                                                        	// Meta is the commit containing the message.
                                                                                        	Meta *GitCommit
                                                                                        
                                                                                        	// Version is the patch set version this message was sent on.
                                                                                        	Version int32
                                                                                        
                                                                                        	// Message is the raw message contents from Gerrit (a subset
                                                                                        	// of the raw git commit message), starting with "Patch Set
                                                                                        	// nnnn".
                                                                                        	Message string
                                                                                        
                                                                                        	// Date is when this message was stored (the commit time of
                                                                                        	// the git commit).
                                                                                        	Date time.Time
                                                                                        
                                                                                        	// Author returns the author of the commit. This takes the form "Gerrit User
                                                                                        	// 13437 <13437@62eb7196-b449-3ce5-99f1-c037f21e1705>", where the number
                                                                                        	// before the '@' sign is your Gerrit user ID, and the UUID after the '@' sign
                                                                                        	// seems to be the same for all commits for the same Gerrit server, across
                                                                                        	// projects.
                                                                                        	//
                                                                                        	// TODO: Merge the *GitPerson object here and for a person's Git commits
                                                                                        	// (which use their real email) via the user ID, so they point to the same
                                                                                        	// object.
                                                                                        	Author *GitPerson
                                                                                        }

                                                                                          GerritMessage is a Gerrit reply that is attached to the CL as a whole, and not to a file or line of a patch set.

                                                                                          Maintner does very little parsing or formatting of a Message body. Messages are stored the same way they are stored in the API.

                                                                                          type GerritMeta

                                                                                          type GerritMeta struct {
                                                                                          	// Commit points up to the git commit for this Gerrit NoteDB meta commit.
                                                                                          	Commit *GitCommit
                                                                                          	// CL is the Gerrit CL this metadata is for.
                                                                                          	CL *GerritCL
                                                                                          	// contains filtered or unexported fields
                                                                                          }

                                                                                            GerritMeta represents a Git commit in the Gerrit NoteDb meta format.

                                                                                            func (*GerritMeta) ActionTag

                                                                                            func (m *GerritMeta) ActionTag() string

                                                                                              ActionTag returns the Gerrit "Tag" value from the meta commit. These are of the form "autogenerated:gerrit:setHashtag".

                                                                                              func (*GerritMeta) Footer

                                                                                              func (m *GerritMeta) Footer() string

                                                                                                Footer returns the "key: value" lines at the base of the commit.

                                                                                                func (*GerritMeta) HashtagEdits

                                                                                                func (m *GerritMeta) HashtagEdits() (added, removed GerritHashtags, ok bool)

                                                                                                  HashtagEdits returns the hashtags added and removed by this meta commit, and whether this meta commit actually modified hashtags.

                                                                                                  func (*GerritMeta) Hashtags

                                                                                                  func (m *GerritMeta) Hashtags() GerritHashtags

                                                                                                    Hashtags returns the set of hashtags on m's CL as of the time of m.

                                                                                                    func (*GerritMeta) HashtagsAdded

                                                                                                    func (m *GerritMeta) HashtagsAdded() GerritHashtags

                                                                                                      HashtagsAdded returns the hashtags added by this meta commit, if any.

                                                                                                      func (*GerritMeta) HashtagsRemoved

                                                                                                      func (m *GerritMeta) HashtagsRemoved() GerritHashtags

                                                                                                        HashtagsRemoved returns the hashtags removed by this meta commit, if any.

                                                                                                        func (*GerritMeta) LabelVotes

                                                                                                        func (m *GerritMeta) LabelVotes() map[string]map[string]int8

                                                                                                          LabelVotes returns a map from label name to voter email to their vote.

                                                                                                          This is relatively expensive to call compared to other methods in maintner. It is not currently cached.

                                                                                                          type GerritProject

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

                                                                                                            GerritProject represents a single Gerrit project.

                                                                                                            func (*GerritProject) CL

                                                                                                            func (gp *GerritProject) CL(number int32) *GerritCL

                                                                                                              CL returns the GerritCL with the given number, or nil if it is not present.

                                                                                                              CL numbers are shared across all projects on a Gerrit server, so you can get nil unless you have the GerritProject containing that CL.

                                                                                                              func (*GerritProject) ForeachCLUnsorted

                                                                                                              func (gp *GerritProject) ForeachCLUnsorted(fn func(*GerritCL) error) error

                                                                                                                ForeachCLUnsorted calls fn for each CL in the repo, in any order.

                                                                                                                If fn returns an error, iteration ends and ForeachCLUnsorted returns with that error.

                                                                                                                func (*GerritProject) ForeachNonChangeRef

                                                                                                                func (gp *GerritProject) ForeachNonChangeRef(fn func(ref string, hash GitHash) error) error

                                                                                                                  ForeachNonChangeRef calls fn for each git ref on the server that is not a change (code review) ref. In general, these correspond to submitted changes. fn is called serially with sorted ref names. Iteration stops with the first non-nil error returned by fn.

                                                                                                                  func (*GerritProject) ForeachOpenCL

                                                                                                                  func (gp *GerritProject) ForeachOpenCL(fn func(*GerritCL) error) error

                                                                                                                    ForeachOpenCL calls fn for each open CL in the repo.

                                                                                                                    If fn returns an error, iteration ends and ForeachOpenCL returns with that error.

                                                                                                                    The fn function is called serially, with increasingly numbered CLs.

                                                                                                                    func (*GerritProject) GitCommit

                                                                                                                    func (gp *GerritProject) GitCommit(hash string) *GitCommit

                                                                                                                      GitCommit returns the provided git commit, or nil if it's unknown.

                                                                                                                      func (*GerritProject) NumLabelChanges

                                                                                                                      func (gp *GerritProject) NumLabelChanges() int

                                                                                                                        NumLabelChanges is an inaccurate count the number of times vote labels have changed in this project. This number is monotonically increasing. This is not guaranteed to be accurate; it definitely overcounts, but it at least increments when changes are made. It will not undercount.

                                                                                                                        func (*GerritProject) Project

                                                                                                                        func (gp *GerritProject) Project() string

                                                                                                                          Project returns the Gerrit project on the server, such as "go" or "crypto".

                                                                                                                          func (*GerritProject) Ref

                                                                                                                          func (gp *GerritProject) Ref(ref string) GitHash

                                                                                                                            Ref returns a non-change ref, such as "HEAD", "refs/heads/master", or "refs/tags/v0.8.0", Change refs of the form "refs/changes/*" are not supported. The returned hash is the zero value (an empty string) if the ref does not exist.

                                                                                                                            func (*GerritProject) Server

                                                                                                                            func (gp *GerritProject) Server() string

                                                                                                                              Server returns the Gerrit server, such as "go.googlesource.com".

                                                                                                                              func (*GerritProject) ServerSlashProject

                                                                                                                              func (gp *GerritProject) ServerSlashProject() string

                                                                                                                                ServerSlashProject returns the server and project together, such as "go.googlesource.com/build".

                                                                                                                                type GitCommit

                                                                                                                                type GitCommit struct {
                                                                                                                                	Hash       GitHash
                                                                                                                                	Tree       GitHash
                                                                                                                                	Parents    []*GitCommit
                                                                                                                                	Author     *GitPerson
                                                                                                                                	AuthorTime time.Time
                                                                                                                                	Committer  *GitPerson
                                                                                                                                	Reviewer   *GitPerson
                                                                                                                                	CommitTime time.Time
                                                                                                                                	Msg        string // Commit message subject and body
                                                                                                                                	Files      []*maintpb.GitDiffTreeFile
                                                                                                                                	GerritMeta *GerritMeta // non-nil if it's a Gerrit NoteDB meta commit
                                                                                                                                }

                                                                                                                                  GitCommit represents a single commit in a git repository.

                                                                                                                                  func (*GitCommit) HasAncestor

                                                                                                                                  func (gc *GitCommit) HasAncestor(ancestor *GitCommit) bool

                                                                                                                                    HasAncestor reports whether gc contains the provided ancestor commit in gc's history.

                                                                                                                                    func (*GitCommit) SameDiffStat

                                                                                                                                    func (gc *GitCommit) SameDiffStat(b *GitCommit) bool

                                                                                                                                      SameDiffStat reports whether gc has the same diff stat numbers as b. If either is unknown, false is returned.

                                                                                                                                      func (*GitCommit) String

                                                                                                                                      func (gc *GitCommit) String() string

                                                                                                                                      func (*GitCommit) Summary

                                                                                                                                      func (gc *GitCommit) Summary() string

                                                                                                                                        Summary returns the first line of the commit message.

                                                                                                                                        type GitHash

                                                                                                                                        type GitHash string

                                                                                                                                          GitHash is a git commit in binary form (NOT hex form). They are currently always 20 bytes long. (for SHA-1 refs) That may change in the future.

                                                                                                                                          func (GitHash) String

                                                                                                                                          func (h GitHash) String() string

                                                                                                                                          type GitHub

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

                                                                                                                                            GitHub holds data about a GitHub repo.

                                                                                                                                            func (*GitHub) ForeachRepo

                                                                                                                                            func (g *GitHub) ForeachRepo(fn func(*GitHubRepo) error) error

                                                                                                                                              ForeachRepo calls fn serially for each GitHubRepo, stopping if fn returns an error. The function is called with lexically increasing repo IDs.

                                                                                                                                              func (*GitHub) Repo

                                                                                                                                              func (g *GitHub) Repo(owner, repo string) *GitHubRepo

                                                                                                                                                Repo returns the repo if it's known. Otherwise it returns nil.

                                                                                                                                                type GitHubComment

                                                                                                                                                type GitHubComment struct {
                                                                                                                                                	ID      int64
                                                                                                                                                	User    *GitHubUser
                                                                                                                                                	Created time.Time
                                                                                                                                                	Updated time.Time
                                                                                                                                                	Body    string
                                                                                                                                                }

                                                                                                                                                type GitHubDismissedReviewEvent

                                                                                                                                                type GitHubDismissedReviewEvent struct {
                                                                                                                                                	ReviewID         int64
                                                                                                                                                	State            string // commented, approved, changes_requested
                                                                                                                                                	DismissalMessage string
                                                                                                                                                }

                                                                                                                                                  GitHubDismissedReview is the contents of a dismissed review event. For more details, see https://developer.github.com/v3/issues/events/.

                                                                                                                                                  type GitHubIssue

                                                                                                                                                  type GitHubIssue struct {
                                                                                                                                                  	ID          int64
                                                                                                                                                  	Number      int32
                                                                                                                                                  	NotExist    bool // if true, rest of fields should be ignored.
                                                                                                                                                  	Closed      bool
                                                                                                                                                  	Locked      bool
                                                                                                                                                  	PullRequest bool // if true, this issue is a Pull Request. All PRs are issues, but not all issues are PRs.
                                                                                                                                                  	User        *GitHubUser
                                                                                                                                                  	Assignees   []*GitHubUser
                                                                                                                                                  	Created     time.Time
                                                                                                                                                  	Updated     time.Time
                                                                                                                                                  	ClosedAt    time.Time
                                                                                                                                                  	ClosedBy    *GitHubUser // TODO(dmitshur): Implement (see golang.org/issue/28745).
                                                                                                                                                  	Title       string
                                                                                                                                                  	Body        string
                                                                                                                                                  	Milestone   *GitHubMilestone       // nil for unknown, noMilestone for none
                                                                                                                                                  	Labels      map[int64]*GitHubLabel // label ID => label
                                                                                                                                                  	// contains filtered or unexported fields
                                                                                                                                                  }

                                                                                                                                                    GitHubIssue represents a GitHub issue. This is maintner's in-memory representation. It differs slightly from the API's *github.Issue type, notably in the lack of pointers for all fields. See https://developer.github.com/v3/issues/#get-a-single-issue

                                                                                                                                                    func (*GitHubIssue) ForeachComment

                                                                                                                                                    func (gi *GitHubIssue) ForeachComment(fn func(*GitHubComment) error) error

                                                                                                                                                      ForeachComment calls fn for each event on the issue.

                                                                                                                                                      If fn returns an error, iteration ends and ForeachComment returns with that error.

                                                                                                                                                      The fn function is called serially, in order of the comment's time.

                                                                                                                                                      func (*GitHubIssue) ForeachEvent

                                                                                                                                                      func (gi *GitHubIssue) ForeachEvent(fn func(*GitHubIssueEvent) error) error

                                                                                                                                                        ForeachEvent calls fn for each event on the issue.

                                                                                                                                                        If fn returns an error, iteration ends and ForeachEvent returns with that error.

                                                                                                                                                        The fn function is called serially, in order of the event's time.

                                                                                                                                                        func (*GitHubIssue) ForeachReview

                                                                                                                                                        func (pr *GitHubIssue) ForeachReview(fn func(*GitHubReview) error) error

                                                                                                                                                          ForeachReview calls fn for each review event on the issue

                                                                                                                                                          If the issue is not a PullRequest, then it returns early with no error.

                                                                                                                                                          If fn returns an error, iteration ends and ForeachReview returns with that error.

                                                                                                                                                          The fn function is called serially, in chronological order.

                                                                                                                                                          func (*GitHubIssue) HasEvent

                                                                                                                                                          func (gi *GitHubIssue) HasEvent(eventType string) bool

                                                                                                                                                            HasEvent reports whether there's any GitHubIssueEvent in this issue's history of the given type.

                                                                                                                                                            func (*GitHubIssue) HasLabel

                                                                                                                                                            func (gi *GitHubIssue) HasLabel(label string) bool

                                                                                                                                                              HasLabel reports whether the issue is labeled with the given label.

                                                                                                                                                              func (*GitHubIssue) HasLabelID

                                                                                                                                                              func (gi *GitHubIssue) HasLabelID(id int64) bool

                                                                                                                                                                HasLabelID returns whether the issue has a label with the given ID.

                                                                                                                                                                func (*GitHubIssue) LastModified

                                                                                                                                                                func (gi *GitHubIssue) LastModified() time.Time

                                                                                                                                                                  LastModified reports the most recent time that any known metadata was updated. In contrast to the Updated field, LastModified includes comments and events.

                                                                                                                                                                  TODO(bradfitz): this seems to not be working, at least events aren't updating it. Investigate.

                                                                                                                                                                  type GitHubIssueEvent

                                                                                                                                                                  type GitHubIssueEvent struct {
                                                                                                                                                                  
                                                                                                                                                                  	// ID is the ID of the event.
                                                                                                                                                                  	ID int64
                                                                                                                                                                  
                                                                                                                                                                  	// Type is one of:
                                                                                                                                                                  	// * labeled, unlabeled
                                                                                                                                                                  	// * milestoned, demilestoned
                                                                                                                                                                  	// * assigned, unassigned
                                                                                                                                                                  	// * locked, unlocked
                                                                                                                                                                  	// * closed
                                                                                                                                                                  	// * referenced
                                                                                                                                                                  	// * renamed
                                                                                                                                                                  	// * reopened
                                                                                                                                                                  	// * comment_deleted
                                                                                                                                                                  	// * head_ref_restored
                                                                                                                                                                  	// * base_ref_changed
                                                                                                                                                                  	// * subscribed
                                                                                                                                                                  	// * mentioned
                                                                                                                                                                  	// * review_requested, review_request_removed, review_dismissed
                                                                                                                                                                  	Type string
                                                                                                                                                                  
                                                                                                                                                                  	// OtherJSON optionally contains a JSON object of GitHub's API
                                                                                                                                                                  	// response for any fields maintner was unable to extract at
                                                                                                                                                                  	// the time. It is empty if maintner supported all the fields
                                                                                                                                                                  	// when the mutation was created.
                                                                                                                                                                  	OtherJSON string
                                                                                                                                                                  
                                                                                                                                                                  	Created time.Time
                                                                                                                                                                  	Actor   *GitHubUser
                                                                                                                                                                  
                                                                                                                                                                  	Label               string      // for type: "unlabeled", "labeled"
                                                                                                                                                                  	Assignee            *GitHubUser // for type "assigned", "unassigned"
                                                                                                                                                                  	Assigner            *GitHubUser // for type "assigned", "unassigned"
                                                                                                                                                                  	Milestone           string      // for type: "milestoned", "demilestoned"
                                                                                                                                                                  	From, To            string      // for type: "renamed"
                                                                                                                                                                  	CommitID, CommitURL string      // for type: "closed", "referenced" ... ?
                                                                                                                                                                  
                                                                                                                                                                  	Reviewer        *GitHubUser
                                                                                                                                                                  	TeamReviewer    *GitHubTeam
                                                                                                                                                                  	ReviewRequester *GitHubUser
                                                                                                                                                                  	DismissedReview *GitHubDismissedReviewEvent
                                                                                                                                                                  }

                                                                                                                                                                  func (*GitHubIssueEvent) Proto

                                                                                                                                                                  type GitHubIssueRef

                                                                                                                                                                  type GitHubIssueRef struct {
                                                                                                                                                                  	Repo   *GitHubRepo // must be non-nil
                                                                                                                                                                  	Number int32       // GitHubIssue.Number
                                                                                                                                                                  }

                                                                                                                                                                    GitHubIssueRef is a reference to an issue (or pull request) number in a repo. These are parsed from text making references such as "golang/go#1234" or just "#1234" (with an implicit Repo).

                                                                                                                                                                    func (GitHubIssueRef) String

                                                                                                                                                                    func (r GitHubIssueRef) String() string

                                                                                                                                                                    type GitHubLabel

                                                                                                                                                                    type GitHubLabel struct {
                                                                                                                                                                    	ID   int64
                                                                                                                                                                    	Name string
                                                                                                                                                                    }

                                                                                                                                                                    func (*GitHubLabel) GenMutationDiff

                                                                                                                                                                    func (a *GitHubLabel) GenMutationDiff(b *github.Label) *maintpb.GithubLabel

                                                                                                                                                                      GenMutationDiff generates a diff from in-memory state 'a' (which may be nil) to the current (non-nil) state b from GitHub. It returns nil if there's no difference.

                                                                                                                                                                      type GitHubMilestone

                                                                                                                                                                      type GitHubMilestone struct {
                                                                                                                                                                      	ID     int64
                                                                                                                                                                      	Title  string
                                                                                                                                                                      	Number int32
                                                                                                                                                                      	Closed bool
                                                                                                                                                                      }

                                                                                                                                                                      func (*GitHubMilestone) GenMutationDiff

                                                                                                                                                                      func (a *GitHubMilestone) GenMutationDiff(b *github.Milestone) *maintpb.GithubMilestone

                                                                                                                                                                        GenMutationDiff generates a diff from in-memory state 'a' (which may be nil) to the current (non-nil) state b from GitHub. It returns nil if there's no difference.

                                                                                                                                                                        func (*GitHubMilestone) IsNone

                                                                                                                                                                        func (ms *GitHubMilestone) IsNone() bool

                                                                                                                                                                          IsNone reports whether ms represents the sentinel "no milestone" milestone.

                                                                                                                                                                          func (*GitHubMilestone) IsUnknown

                                                                                                                                                                          func (ms *GitHubMilestone) IsUnknown() bool

                                                                                                                                                                            IsUnknown reports whether ms is nil, which represents the unknown state. Milestones should never be in this state, though.

                                                                                                                                                                            type GitHubRepo

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

                                                                                                                                                                            func (*GitHubRepo) ForeachIssue

                                                                                                                                                                            func (gr *GitHubRepo) ForeachIssue(fn func(*GitHubIssue) error) error

                                                                                                                                                                              ForeachIssue calls fn for each issue in the repo.

                                                                                                                                                                              If fn returns an error, iteration ends and ForeachIssue returns with that error.

                                                                                                                                                                              The fn function is called serially, with increasingly numbered issues.

                                                                                                                                                                              func (*GitHubRepo) ForeachLabel

                                                                                                                                                                              func (gr *GitHubRepo) ForeachLabel(fn func(*GitHubLabel) error) error

                                                                                                                                                                                ForeachLabel calls fn for each label in the repo, in unsorted order.

                                                                                                                                                                                Iteration ends if fn returns an error, with that error.

                                                                                                                                                                                func (*GitHubRepo) ForeachMilestone

                                                                                                                                                                                func (gr *GitHubRepo) ForeachMilestone(fn func(*GitHubMilestone) error) error

                                                                                                                                                                                  ForeachMilestone calls fn for each milestone in the repo, in unsorted order.

                                                                                                                                                                                  Iteration ends if fn returns an error, with that error.

                                                                                                                                                                                  func (*GitHubRepo) ID

                                                                                                                                                                                  func (gr *GitHubRepo) ID() GitHubRepoID

                                                                                                                                                                                  func (*GitHubRepo) Issue

                                                                                                                                                                                  func (gr *GitHubRepo) Issue(n int32) *GitHubIssue

                                                                                                                                                                                    Issue returns the the provided issue number, or nil if it's not known.

                                                                                                                                                                                    type GitHubRepoID

                                                                                                                                                                                    type GitHubRepoID struct {
                                                                                                                                                                                    	Owner, Repo string
                                                                                                                                                                                    }

                                                                                                                                                                                      GitHubRepoID is a GitHub org & repo, lowercase.

                                                                                                                                                                                      func (GitHubRepoID) String

                                                                                                                                                                                      func (id GitHubRepoID) String() string

                                                                                                                                                                                      type GitHubReview

                                                                                                                                                                                      type GitHubReview struct {
                                                                                                                                                                                      	ID               int64
                                                                                                                                                                                      	Actor            *GitHubUser
                                                                                                                                                                                      	Body             string
                                                                                                                                                                                      	State            string // COMMENTED, APPROVED, CHANGES_REQUESTED
                                                                                                                                                                                      	CommitID         string
                                                                                                                                                                                      	ActorAssociation string // CONTRIBUTOR
                                                                                                                                                                                      	Created          time.Time
                                                                                                                                                                                      	OtherJSON        string
                                                                                                                                                                                      }

                                                                                                                                                                                        GitHubReview represents a review on a Pull Request. For more details, see https://developer.github.com/v3/pulls/reviews/

                                                                                                                                                                                        func (*GitHubReview) Proto

                                                                                                                                                                                        func (e *GitHubReview) Proto() *maintpb.GithubReview

                                                                                                                                                                                          Proto converts GitHubReview to a protobuf

                                                                                                                                                                                          type GitHubTeam

                                                                                                                                                                                          type GitHubTeam struct {
                                                                                                                                                                                          	ID int64
                                                                                                                                                                                          
                                                                                                                                                                                          	// Slug is a URL-friendly representation of the team name.
                                                                                                                                                                                          	// It is unique across a GitHub organization.
                                                                                                                                                                                          	Slug string
                                                                                                                                                                                          }

                                                                                                                                                                                            GitHubTeam represents a GitHub team. It is a subset of https://developer.github.com/v3/orgs/teams/#get-team

                                                                                                                                                                                            type GitHubUser

                                                                                                                                                                                            type GitHubUser struct {
                                                                                                                                                                                            	ID    int64
                                                                                                                                                                                            	Login string
                                                                                                                                                                                            }

                                                                                                                                                                                              GitHubUser represents a GitHub user. It is a subset of https://developer.github.com/v3/users/#get-a-single-user

                                                                                                                                                                                              type GitPerson

                                                                                                                                                                                              type GitPerson struct {
                                                                                                                                                                                              	Str string // "Foo Bar <foo@bar.com>"
                                                                                                                                                                                              }

                                                                                                                                                                                                GitPerson is a person in a git commit.

                                                                                                                                                                                                func (*GitPerson) Email

                                                                                                                                                                                                func (p *GitPerson) Email() string

                                                                                                                                                                                                  Email returns the GitPerson's email address only, without the name or angle brackets.

                                                                                                                                                                                                  func (*GitPerson) Name

                                                                                                                                                                                                  func (p *GitPerson) Name() string

                                                                                                                                                                                                  func (*GitPerson) String

                                                                                                                                                                                                  func (p *GitPerson) String() string

                                                                                                                                                                                                    String implements fmt.Stringer.

                                                                                                                                                                                                    type LogSegmentJSON

                                                                                                                                                                                                    type LogSegmentJSON struct {
                                                                                                                                                                                                    	Number int    `json:"number"`
                                                                                                                                                                                                    	Size   int64  `json:"size"`
                                                                                                                                                                                                    	SHA224 string `json:"sha224"`
                                                                                                                                                                                                    	URL    string `json:"url"`
                                                                                                                                                                                                    }

                                                                                                                                                                                                    type MutationLogger

                                                                                                                                                                                                    type MutationLogger interface {
                                                                                                                                                                                                    	Log(*maintpb.Mutation) error
                                                                                                                                                                                                    }

                                                                                                                                                                                                      A MutationLogger logs mutations.

                                                                                                                                                                                                      type MutationSource

                                                                                                                                                                                                      type MutationSource interface {
                                                                                                                                                                                                      	// GetMutations returns a channel of mutations or related events.
                                                                                                                                                                                                      	// The channel will never be closed.
                                                                                                                                                                                                      	// All sends on the returned channel should select
                                                                                                                                                                                                      	// on the provided context.
                                                                                                                                                                                                      	GetMutations(context.Context) <-chan MutationStreamEvent
                                                                                                                                                                                                      }

                                                                                                                                                                                                        A MutationSource yields a log of mutations that will catch a corpus back up to the present.

                                                                                                                                                                                                        func NewNetworkMutationSource

                                                                                                                                                                                                        func NewNetworkMutationSource(server, cacheDir string) MutationSource

                                                                                                                                                                                                          NewNetworkMutationSource returns a mutation source from a master server. The server argument should be a URL to the JSON logs index.

                                                                                                                                                                                                          type MutationStreamEvent

                                                                                                                                                                                                          type MutationStreamEvent struct {
                                                                                                                                                                                                          	Mutation *maintpb.Mutation
                                                                                                                                                                                                          
                                                                                                                                                                                                          	// Err is a fatal error reading the log. No other events will
                                                                                                                                                                                                          	// follow an Err.
                                                                                                                                                                                                          	Err error
                                                                                                                                                                                                          
                                                                                                                                                                                                          	// End, if true, means that all mutations have been sent and
                                                                                                                                                                                                          	// the next event might take some time to arrive (it might not
                                                                                                                                                                                                          	// have occurred yet). The End event is not a terminal state
                                                                                                                                                                                                          	// like Err. There may be multiple Ends.
                                                                                                                                                                                                          	End bool
                                                                                                                                                                                                          }

                                                                                                                                                                                                            MutationStreamEvent represents one of three possible events while reading mutations from disk or another source. An event is either a mutation, an error, or reaching the current end of the log. Exactly one of the three fields will be non-zero.

                                                                                                                                                                                                            Directories

                                                                                                                                                                                                            Path Synopsis
                                                                                                                                                                                                            cmd
                                                                                                                                                                                                            maintserve Module
                                                                                                                                                                                                            Package godata loads the Go project's corpus of Git, Github, and Gerrit activity into memory to allow easy analysis without worrying about APIs and their pagination, quotas, and other nuisances and limitations.
                                                                                                                                                                                                            Package godata loads the Go project's corpus of Git, Github, and Gerrit activity into memory to allow easy analysis without worrying about APIs and their pagination, quotas, and other nuisances and limitations.
                                                                                                                                                                                                            The gostats command computes stats about the Go project.
                                                                                                                                                                                                            The gostats command computes stats about the Go project.
                                                                                                                                                                                                            The maintnerd command serves project maintainer data from Git, Github, and/or Gerrit.
                                                                                                                                                                                                            The maintnerd command serves project maintainer data from Git, Github, and/or Gerrit.
                                                                                                                                                                                                            apipb
                                                                                                                                                                                                            Package apipb is a generated protocol buffer package.
                                                                                                                                                                                                            Package apipb is a generated protocol buffer package.
                                                                                                                                                                                                            gcslog
                                                                                                                                                                                                            Package gcslog is an implementation of maintner.MutationSource and Logger for Google Cloud Storage.
                                                                                                                                                                                                            Package gcslog is an implementation of maintner.MutationSource and Logger for Google Cloud Storage.
                                                                                                                                                                                                            maintapi
                                                                                                                                                                                                            Package maintapi exposes a gRPC maintner service for a given corpus.
                                                                                                                                                                                                            Package maintapi exposes a gRPC maintner service for a given corpus.
                                                                                                                                                                                                            maintapi/version
                                                                                                                                                                                                            Package version implements logic to parse version of Go tags and release branches.
                                                                                                                                                                                                            Package version implements logic to parse version of Go tags and release branches.
                                                                                                                                                                                                            Package maintpb is a generated protocol buffer package.
                                                                                                                                                                                                            Package maintpb is a generated protocol buffer package.
                                                                                                                                                                                                            The maintq command queries a maintnerd gRPC server.
                                                                                                                                                                                                            The maintq command queries a maintnerd gRPC server.
                                                                                                                                                                                                            The maintwatch commands tails the maintner mutation log.
                                                                                                                                                                                                            The maintwatch commands tails the maintner mutation log.
                                                                                                                                                                                                            Package reclog contains readers and writers for a record wrapper format used by maintner.
                                                                                                                                                                                                            Package reclog contains readers and writers for a record wrapper format used by maintner.