deprecate packages sets, retry, github; release v0.14.0

The deprecation warnings will be picked up by the documentation shown
on https://pkg.go.dev/github.com/Pix4D/cogito and by any IDE that is Go-aware.

PCI-4471

Author: marco-m-pix4d

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.14.0] - 2026-01-22
+
+### Deprecated
+
+- All APIs in packages `sets`, `retry`, `github` are DEPRECATED. Will be removed in the next release.
+  This does not impact the users of the cogito Concourse resource.
+  It impacts only code using these packages directly. Such code should switch to https://github.com/Pix4D/go-kit, which contains the same packages (drop-in replacement).
+
 ## [v0.13.0] - 2025-05-05
 
 ### Added

github/commitstatus.go

@@ -2,6 +2,8 @@
 //
 // See the README and CONTRIBUTING files for additional information, caveats about GitHub
 // API and imposed limits, and reference to official documentation.
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 package github
 
 import (
@@ -22,12 +24,15 @@ import (
 )
 
 // StatusError is one of the possible errors returned by the github package.
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 type StatusError struct {
 	What       string
 	StatusCode int
 	Details    string
 }
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func (e *StatusError) Error() string {
 	return fmt.Sprintf("%s\n%s", e.What, e.Details)
 }
@@ -37,6 +42,7 @@ const GhDefaultHostname = "github.com"
 
 var localhostRegexp = regexp.MustCompile(`^127.0.0.1:[0-9]+$`)
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 type Target struct {
 	// Client is the http client
 	Client *http.Client
@@ -51,6 +57,8 @@ type Target struct {
 // See also:
 // - NewCommitStatus
 // - https://docs.github.com/en/rest/commits/statuses
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 type CommitStatus struct {
 	target  *Target
 	token   string
@@ -72,6 +80,8 @@ type CommitStatus struct {
 //
 // See also:
 // - https://docs.github.com/en/rest/commits/statuses
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func NewCommitStatus(
 	target *Target,
 	token, owner, repo, context string,
@@ -88,6 +98,8 @@ func NewCommitStatus(
 }
 
 // AddRequest is the JSON object sent to the API.
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 type AddRequest struct {
 	State       string `json:"state"`
 	TargetURL   string `json:"target_url"`
@@ -108,6 +120,8 @@ type AddRequest struct {
 // The returned error contains some diagnostic information to help troubleshooting.
 //
 // See also: https://docs.github.com/en/rest/commits/statuses#create-a-commit-status
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func (cs CommitStatus) Add(ctx context.Context, sha, state, targetURL, description string) error {
 	// API: POST /repos/{owner}/{repo}/statuses/{sha}
 	url := cs.target.Server + path.Join("/repos", cs.owner, cs.repo, "statuses", sha)
@@ -236,6 +250,8 @@ func (cs CommitStatus) explainError(err error, state, sha, url string) error {
 // if hostname looks like a httptest server, it returns http://127.0.0.1:PORT
 // otherwise, hostname is assumed to be of a Github Enterprise instance.
 // For example, github.mycompany.org returns https://github.mycompany.org/api/v3
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func ApiRoot(h string) string {
 	hostname := strings.ToLower(h)
 	if hostname == GhDefaultHostname {

github/githubapp.go

@@ -13,12 +13,14 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 )
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 type GitHubApp struct {
 	ClientId       string `json:"client_id"`
 	InstallationId int    `json:"installation_id"`
 	PrivateKey     string `json:"private_key"` // SENSITIVE
 }
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func (app *GitHubApp) IsZero() bool {
 	return *app == GitHubApp{}
 }
@@ -54,6 +56,8 @@ func generateJWTtoken(clientId, privateKey string) (string, error) {
 }
 
 // GenerateInstallationToken returns an installation token used to authenticate as GitHub App installation
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func GenerateInstallationToken(ctx context.Context, client *http.Client, server string, app GitHubApp) (string, error) {
 	// API: POST /app/installations/{installationId}/access_tokens
 	installationId := strconv.Itoa(app.InstallationId)

github/githuberror.go

@@ -7,6 +7,7 @@ import (
 	"time"
 )
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 type GitHubError struct {
 	StatusCode         int
 	OauthInfo          string
@@ -16,6 +17,7 @@ type GitHubError struct {
 	innerErr           error
 }
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func NewGitHubError(httpResp *http.Response, innerErr error) error {
 	ghErr := GitHubError{
 		innerErr:   innerErr,
@@ -73,10 +75,12 @@ func NewGitHubError(httpResp *http.Response, innerErr error) error {
 	return ghErr
 }
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func (ghe GitHubError) Error() string {
 	return ghe.innerErr.Error()
 }
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func (ghe GitHubError) Unwrap() error {
 	return ghe.innerErr
 }

github/retry.go

@@ -11,6 +11,8 @@ import (
 )
 
 // Classifier implements [retry.ClassifierFunc] for GitHub.
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func Classifier(err error) retry.Action {
 	if err == nil {
 		return retry.Success
@@ -31,6 +33,8 @@ func Classifier(err error) retry.Action {
 }
 
 // Backoff implements [retry.BackoffFunc] for GitHub.
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func Backoff(first bool, previous, limit time.Duration, err error) time.Duration {
 	// Optimization: Are we rate limited?
 	// This allows to immediately terminate the retry loop if it would take too
@@ -62,12 +66,16 @@ func Backoff(first bool, previous, limit time.Duration, err error) time.Duration
 
 // RateLimited returns true if the http.Response in err reports being rate limited.
 // See https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#exceeding-the-rate-limit
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func RateLimited(err GitHubError) bool {
 	return err.StatusCode == http.StatusForbidden && err.RateLimitRemaining == 0
 }
 
 // TransientError returns true if the http.Response in err has a status code
 // that can be retried.
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func TransientError(statusCode int) bool {
 	switch statusCode {
 	case

github/url.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 )
 
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 type GitURL struct {
 	URL      *url.URL
 	Owner    string
@@ -42,6 +43,8 @@ func safeUrlParse(rawURL string) (*url.URL, error) {
 //   - https with u:p: 	https//username:password@github.com/Pix4D/cogito.git
 //   - http: 			http://github.com/Pix4D/cogito.git
 //   - http with u:p: 	http://username:password@github.com/Pix4D/cogito.git
+//
+// Deprecated: Package github is replaced by github.com/Pix4D/go-kit/github.
 func ParseGitPseudoURL(rawURL string) (GitURL, error) {
 	workURL := rawURL
 	// If ssh pseudo URL, we need to massage the rawURL ourselves :-(

retry/backoff.go

@@ -4,10 +4,12 @@ import (
 	"time"
 )
 
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 func ConstantBackoff(first bool, previous, limit time.Duration, err error) time.Duration {
 	return min(previous, limit)
 }
 
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 func ExponentialBackoff(first bool, previous, limit time.Duration, err error) time.Duration {
 	if first {
 		return previous

retry/retry.go

@@ -2,6 +2,8 @@
 //
 // Took some inspiration from:
 // - https://github.com/eapache/go-resiliency/tree/main/retrier
+//
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 package retry
 
 import (
@@ -11,6 +13,8 @@ import (
 )
 
 // Action is returned by a ClassifierFunc to indicate to Retry how to proceed.
+//
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 type Action int
 
 const (
@@ -26,6 +30,8 @@ const (
 
 // Retry is the controller of the retry mechanism.
 // See the examples in file retry_example_test.go.
+//
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 type Retry struct {
 	UpTo         time.Duration // Total maximum duration of the retries.
 	FirstDelay   time.Duration // Duration of the first backoff.
@@ -41,19 +47,27 @@ type Retry struct {
 // and return a custom delay; this can be used in special cases such as when
 // rate-limited with a fixed window; for an example see
 // [github.com/Pix4D/cogito/github.Backoff].
+//
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 type BackoffFunc func(first bool, previous, limit time.Duration, err error) time.Duration
 
 // ClassifierFunc decides whether to proceed or not; called by [Retry.Do].
 // Parameter err allows to inspect the error; for an example see
 // [github.com/Pix4D/cogito/github.Classifier]
+//
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 type ClassifierFunc func(err error) Action
 
 // WorkFunc does the unit of work that might fail and need to be retried; called
 // by [Retry.Do].
+//
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 type WorkFunc func() error
 
 // Do is the loop of [Retry].
 // See the examples in file retry_example_test.go.
+//
+// Deprecated: Package retry is replaced by github.com/Pix4D/go-kit/retry.
 func (rtr Retry) Do(
 	backoffFn BackoffFunc,
 	classifierFn ClassifierFunc,

sets/sets.go

@@ -1,5 +1,6 @@
 // Package sets is a minimal implementation of a generic set data structure.
-
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 package sets
 
 import (
@@ -10,17 +11,23 @@ import (
 
 // Set is a minimal set that takes only ordered types: any type that supports the
 // operators < <= >= >.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 type Set[T cmp.Ordered] struct {
 	items map[T]struct{}
 }
 
 // New returns an empty set with capacity size. The capacity will grow and shrink as a
 // stdlib map.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func New[T cmp.Ordered](size int) *Set[T] {
 	return &Set[T]{items: make(map[T]struct{}, size)}
 }
 
 // From returns a set from elements.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func From[T cmp.Ordered](elements ...T) *Set[T] {
 	s := New[T](len(elements))
 	for _, i := range elements {
@@ -32,17 +39,22 @@ func From[T cmp.Ordered](elements ...T) *Set[T] {
 // String returns a string representation of s, ordered. This allows to simply pass a
 // sets.Set as parameter to a function that expects a fmt.Stringer interface and obtain
 // a comparable string.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) String() string {
 	return fmt.Sprint(s.OrderedList())
 }
 
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) Size() int {
 	return len(s.items)
 }
 
 // OrderedList returns a slice of the elements of s, ordered.
 // TODO This can probably be replaced in Go 1.20 when a generics slice packages reaches
 // the stdlib.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) OrderedList() []T {
 	elements := make([]T, 0, len(s.items))
 	for e := range s.items {
@@ -55,12 +67,16 @@ func (s *Set[T]) OrderedList() []T {
 }
 
 // Contains returns true if s contains item.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) Contains(item T) bool {
 	_, found := s.items[item]
 	return found
 }
 
 // Add inserts item into s. Returns true if the item was present.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) Add(item T) bool {
 	if s.Contains(item) {
 		return true
@@ -70,6 +86,8 @@ func (s *Set[T]) Add(item T) bool {
 }
 
 // Remove deletes item from s. Returns true if the item was present.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) Remove(item T) bool {
 	if !s.Contains(item) {
 		return false
@@ -79,6 +97,8 @@ func (s *Set[T]) Remove(item T) bool {
 }
 
 // Difference returns a set containing the elements of s that are not in x.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) Difference(x *Set[T]) *Set[T] {
 	result := New[T](max(0, s.Size()-x.Size()))
 	for item := range s.items {
@@ -90,6 +110,8 @@ func (s *Set[T]) Difference(x *Set[T]) *Set[T] {
 }
 
 // Intersection returns a set containing the elements that are both in s and x.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) Intersection(x *Set[T]) *Set[T] {
 	result := New[T](0)
 	// loop over the smaller set (thanks to https://github.com/deckarep/golang-set)
@@ -107,6 +129,8 @@ func (s *Set[T]) Intersection(x *Set[T]) *Set[T] {
 }
 
 // Union returns a set containing all the elements of s and x.
+//
+// Deprecated: Package sets is replaced by github.com/Pix4D/go-kit/sets.
 func (s *Set[T]) Union(x *Set[T]) *Set[T] {
 	result := New[T](max(s.Size(), x.Size()))
 	for item := range s.items {