Release Notes v0.6.0

This release adds the graphql package for GitHub GraphQL API support, providing user contribution statistics similar to what's shown on GitHub profile pages. It also introduces a comprehensive MkDocs documentation site.

New Features

GraphQL Package for Contribution Statistics

The new graphql package provides access to GitHub's GraphQL API for retrieving user contribution statistics. Two approaches are available depending on your needs:

Quick Stats (Profile View)

Fast retrieval using contributionsCollection - the same data that powers GitHub profile contribution graphs:

import "github.com/grokify/gogithub/graphql"

client := graphql.NewClient(ctx, "your-token")

from := time.Now().AddDate(-1, 0, 0)
to := time.Now()

stats, err := graphql.GetContributionStats(ctx, client, "octocat", from, to)
if err != nil {
    return err
}

fmt.Printf("Total commits: %d\n", stats.TotalCommitContributions)
fmt.Printf("Total PRs: %d\n", stats.TotalPRContributions)
fmt.Printf("Total issues: %d\n", stats.TotalIssueContributions)

For queries spanning more than one year (the API limit), use GetContributionStatsMultiYear:

from := time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)
to := time.Now()

stats, err := graphql.GetContributionStatsMultiYear(ctx, client, "octocat", from, to)

Detailed Stats (Additions/Deletions)

For line-level statistics with public/private filtering, use the detailed stats functions:

// Get stats for all repositories
stats, err := graphql.GetCommitStats(ctx, client, "octocat", from, to, graphql.VisibilityAll)

fmt.Printf("Commits: %d\n", stats.TotalCommits)
fmt.Printf("Additions: %d\n", stats.Additions)
fmt.Printf("Deletions: %d\n", stats.Deletions)

// Monthly breakdown
for _, month := range stats.ByMonth {
    fmt.Printf("%s: %d commits (+%d/-%d)\n",
        month.YearMonth(), month.Commits, month.Additions, month.Deletions)
}

// Per-repository breakdown
for _, repo := range stats.ByRepo {
    fmt.Printf("%s/%s: %d commits\n", repo.Owner, repo.Name, repo.Commits)
}

Visibility Filtering

Filter statistics by repository visibility:

// Public repositories only
public, err := graphql.GetCommitStats(ctx, client, "octocat", from, to, graphql.VisibilityPublic)

// Private repositories only
private, err := graphql.GetCommitStats(ctx, client, "octocat", from, to, graphql.VisibilityPrivate)

// Get all three at once
all, public, private, err := graphql.GetCommitStatsByVisibility(ctx, client, "octocat", from, to)

Comparison of Approaches

Feature	GetContributionStats	GetCommitStats
Speed	Fast (1 query/year)	Slower (paginated)
Commit count	✅	✅
Additions/Deletions	❌	✅
Public/Private split	⚠️ Combined only	✅ Precise
Monthly breakdown	✅ All contributions	✅ Commits only
Per-repo breakdown	❌	✅

MkDocs Documentation Site

A comprehensive documentation site is now available at grokify.github.io/gogithub:

• Getting Started - Installation and quick start guide
• Package Guides - Detailed documentation for each package
• API Reference - Links to pkg.go.dev documentation
• Changelog - Version history

The site uses MkDocs with Material theme and is automatically deployed via GitHub Actions.

New Types

graphql.ContributionStats

type ContributionStats struct {
    Username                     string
    From                         time.Time
    To                           time.Time
    TotalCommitContributions     int
    TotalIssueContributions      int
    TotalPRContributions         int
    TotalPRReviewContributions   int
    TotalRepositoryContributions int
    RestrictedContributions      int  // All private contributions
    ContributionsByMonth         []MonthlyContribution
}

graphql.CommitStats

type CommitStats struct {
    Username     string
    From         time.Time
    To           time.Time
    Visibility   Visibility
    TotalCommits int
    Additions    int
    Deletions    int
    ByMonth      []MonthlyCommitStats
    ByRepo       []RepoCommitStats
}

graphql.Visibility

const (
    VisibilityAll     Visibility = iota  // All repositories
    VisibilityPublic                      // Public only
    VisibilityPrivate                     // Private only
)

Dependencies

• Added github.com/shurcooL/githubv4 for GitHub GraphQL API support

Authentication Note

The GraphQL API always requires authentication, even for public data. A token with no special scopes is sufficient for querying public repositories:

// Works for public data - no special scopes needed
client := graphql.NewClient(ctx, "your-token")

For GitHub Enterprise:

client := graphql.NewEnterpriseClient(ctx, "your-token", "https://github.mycompany.com/api/graphql")