Added some godoc

pkg/patch/patch.go

@@ -42,6 +42,7 @@ type TemplateContextRegex struct {
 	Groups []string
 }
 
+// ApplyMany applies a series of patches in sequence using [Apply].
 func ApplyMany(repoDir string, patches []config.PackageRepoPatch, tmplCtx TemplateContext) error {
 	for _, p := range patches {
 		if err := Apply(repoDir, p, tmplCtx); err != nil {
@@ -51,6 +52,7 @@ func ApplyMany(repoDir string, patches []config.PackageRepoPatch, tmplCtx Templa
 	return nil
 }
 
+// Apply applies a single patch to the repository.
 func Apply(repoDir string, patch config.PackageRepoPatch, tmplCtx TemplateContext) error {
 	// TODO: Check that the patch path doesn't go outside the repo dir.
 	// For example, reject stuff like "../../../somefile.txt"

pkg/patch/patcher.go

@@ -35,11 +35,16 @@ var (
 	ErrNoPatches = errors.New("no patches configured for repository")
 )
 
+// Patcher is the manager for managing repositories and patching them,
+// as well as pushing the changes in form of GitHub pull requests.
+//
+// This is the main integration code between the other packages.
 type Patcher struct {
 	cfg *config.Config
 	gh  github.Client
 }
 
+// New creates a new [Patcher] using a base config.
 func New(cfg *config.Config) (Patcher, error) {
 	gh, err := github.New(&cfg.GitHub)
 	if err != nil {
@@ -51,18 +56,26 @@ func New(cfg *config.Config) (Patcher, error) {
 	}, nil
 }
 
+// CloneWithConfig creates a copy of this object, but with a new [config.Config]
+// applied. Useful if you want to change just a few fields, such as the dry-run
+// setting, while still reusing the GitHub App cache.
 func (p Patcher) CloneWithConfig(cfg *config.Config) Patcher {
 	p.cfg = cfg
 	return p
 }
 
+// TestGitHubConnection is practically a ping towards GitHub, to ensure the
+// credentials from the config are working.
 func (p Patcher) TestGitHubConnection(ctx context.Context) error {
 	if err := p.gh.TestConnection(context.TODO()); err != nil {
 		return fmt.Errorf("test GitHub connection: %w", err)
 	}
 	return nil
 }
 
+// CloneAndPublishAll will clone a list of Git repository, apply all the
+// configured patches, and then publish the changes in the form of GitHub
+// pull requests.
 func (p Patcher) CloneAndPublishAll(pkgRepos []config.PackageRepo, tmplCtx TemplateContext) ([]github.PullRequest, error) {
 	if len(pkgRepos) == 0 {
 		log.Warn().Str("package", tmplCtx.Package).Msg("No repos configured for package.")
@@ -86,6 +99,8 @@ func (p Patcher) CloneAndPublishAll(pkgRepos []config.PackageRepo, tmplCtx Templ
 	return prs, nil
 }
 
+// CloneAndPublishRepo will clone a Git repository, apply all the configured
+// patches, and then publish the changes in the form of a GitHub pull requests.
 func (p Patcher) CloneAndPublishRepo(pkgRepo config.PackageRepo, tmplCtx TemplateContext) (github.PullRequest, error) {
 	repo, err := p.CloneRepo(pkgRepo.URL, tmplCtx)
 	if err != nil {
@@ -101,6 +116,8 @@ func (p Patcher) CloneAndPublishRepo(pkgRepo config.PackageRepo, tmplCtx Templat
 	return repo.PublishChangesUnlessDryRun(commit)
 }
 
+// CloneRepo will download a Git repository from GitHub using the configured
+// credentials. It is cloned using HTTPS instead of SSH.
 func (p Patcher) CloneRepo(remote string, tmplCtx TemplateContext) (*Repo, error) {
 	// Check this early so we don't fail right on the finish line
 	ghRef, err := github.ParseRepoRef(remote)

pkg/patch/repo.go

@@ -28,6 +28,8 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
+// Repo is an object to manage patches for a single repository.
+// It is obtained from the [Patcher] object.
 type Repo struct {
 	gh      github.Client
 	ghRef   github.RepoRef
@@ -37,6 +39,7 @@ type Repo struct {
 	tmplCtx TemplateContext
 }
 
+// Close cleans up the Git repository by removing the entire directory.
 func (p *Repo) Close() error {
 	err := p.repo.Close()
 	if err != nil {
@@ -49,6 +52,8 @@ func (p *Repo) Close() error {
 	return err
 }
 
+// ApplyManyAndCommit uses [ApplyManyInNewBranch] to apply a series of patches
+// in a new Git branch, followed by creating a Git commit.
 func (p *Repo) ApplyManyAndCommit(patches []config.PackageRepoPatch) (git.Commit, error) {
 	if len(patches) == 0 {
 		log.Warn().
@@ -83,6 +88,8 @@ func (p *Repo) ApplyManyAndCommit(patches []config.PackageRepoPatch) (git.Commit
 	return commit, nil
 }
 
+// ApplyManyInNewBranch creates a new Git branch and then applies multiple
+// patches in series using [ApplyMany].
 func (p *Repo) ApplyManyInNewBranch(patches []config.PackageRepoPatch) error {
 	branchName, err := p.cfg.GitHub.PR.Branch.Render(p.tmplCtx)
 	if err != nil {
@@ -102,6 +109,12 @@ func (p *Repo) ApplyManyInNewBranch(patches []config.PackageRepoPatch) error {
 	return nil
 }
 
+// PublishChangesUnlessDryRun calls [PublishChanges], unless dry-run is set
+// in the configs.
+//
+// If dry-run is enabled, then this function templates all PR fields
+// (title, description, etc), and then returns it as-is without pushing anything
+// to the Git remote.
 func (p *Repo) PublishChangesUnlessDryRun(commit git.Commit) (github.PullRequest, error) {
 	if p.cfg.DryRun {
 		log.Info().Msg("Dry run: skipping publishing changes.")
@@ -126,6 +139,8 @@ func (p *Repo) PublishChangesUnlessDryRun(commit git.Commit) (github.PullRequest
 	return pr, nil
 }
 
+// PublishChanges will push the current Git branch to the remote, and then
+// create a GitHub pull request.
 func (p *Repo) PublishChanges(commit git.Commit) (github.PullRequest, error) {
 	if err := p.repo.PushChanges(); err != nil {
 		return github.PullRequest{}, err
@@ -148,6 +163,8 @@ func (p *Repo) PublishChanges(commit git.Commit) (github.PullRequest, error) {
 	return pr, nil
 }
 
+// TemplateNewPullRequest will template using [text/template] the pull request
+// fields (title, description, etc), based on what's set in the config.
 func (p *Repo) TemplateNewPullRequest(commit git.Commit) (github.NewPullRequest, error) {
 	title, err := p.cfg.GitHub.PR.Title.Render(p.tmplCtx)
 	if err != nil {
@@ -168,6 +185,8 @@ func (p *Repo) TemplateNewPullRequest(commit git.Commit) (github.NewPullRequest,
 	}, nil
 }
 
+// logDiff sends a log message with a commit diff. Will optionally colorize it
+// if log format is set to "pretty".
 func (p *Repo) logDiff(diff string) {
 	if log.Logger.GetLevel() > zerolog.DebugLevel {
 		return