From 78d6200ef964548341c4ca8a17c96cce7c5d8e56 Mon Sep 17 00:00:00 2001 From: MacLane S Wilkison Date: Wed, 16 Sep 2026 14:23:29 -0500 Subject: [PATCH] docs: prepare standalone keep-common deprecation --- CHANGELOG.md | 5 ++- CONTRIBUTING.adoc | 11 ++++-- DEPRECATION.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++ README.adoc | 30 +++++++++++++--- RELEASE.md | 11 +++++- 5 files changed, 137 insertions(+), 9 deletions(-) create mode 100644 DEPRECATION.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 147dd25..3f48a9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,11 @@ All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this fork follows Semantic Versioning for tagged releases. ## Unreleased +### Deprecated +- Plan retirement of this standalone Threshold fork after keep-core's release candidate lands and remaining consumers are reviewed. Runtime code and generators already live in keep-core; preserve existing module/repository coordinates and immutable tags. See [DEPRECATION.md](DEPRECATION.md). + ### Added -- Release guide and initial changelog stub for the fork of `keep-core/keep-common`. +- Release guide and initial changelog stub for the fork of `keep-network/keep-common`. ### Changed - Bump minimum Go toolchain to 1.26.8 to include standard library security fixes; CI and releases read this version from `go.mod`. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 1856dea..aeaa6f7 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -7,12 +7,19 @@ The following is a set of guidelines for contributing. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. +== Maintenance status + +This standalone fork is being deprecated; see link:DEPRECATION.md[Deprecation plan]. +New development of the absorbed libraries and generators belongs in `keep-core`. +Coordinate any maintenance work needed by retained consumers through +https://github.com/threshold-network/keep-common/issues/33[the retirement tracker]. + == Getting started -1. Fork https://github.com/keep-network/keep-common[`keep-network/keep-common`] +1. Fork https://github.com/threshold-network/keep-common[`threshold-network/keep-common`] 2. Clone your fork 3. Follow the -https://github.com/keep-network/keep-common/blob/main/README.adoc[installation +https://github.com/threshold-network/keep-common/blob/main/README.adoc[installation steps] in the README. 4. Enable https://help.github.com/en/articles/about-commit-signature-verification[commit diff --git a/DEPRECATION.md b/DEPRECATION.md new file mode 100644 index 0000000..43752d8 --- /dev/null +++ b/DEPRECATION.md @@ -0,0 +1,89 @@ +# Deprecating the standalone Threshold fork + +`threshold-network/keep-common` is being retired as a standalone library. Keep +its existing repository name and `github.com/keep-network/keep-common` module +identity. There will be no `threshold-common` rename or replacement module. + +This decision applies only to the Threshold fork. The original +`keep-network/keep-common` repository and other organizations' forks have their +own owners and maintenance policies. + +## Why keep-core no longer needs it + +At the reviewed release-candidate commit +[`a90ce1bf0738a35e4e3881f634f07520c2b8529e`](https://github.com/threshold-network/keep-core/tree/a90ce1bf0738a35e4e3881f634f07520c2b8529e), +keep-core has incorporated both the runtime packages and code generators from +this repository through [PR #4327](https://github.com/threshold-network/keep-core/pull/4327). +Its `go.mod`, `go.sum`, imports, and generator commands no longer consume this +module. The sole remaining `keep-common` string is a historical link to the +original upstream issue #117, not a build dependency. + +The final incorporated package layout is not `pkg/keepcommon`. Runtime packages +were flattened into keep-core (for example `pkg/persistence` and +`pkg/chain/ethereumutil`), and the generator is local at +`tools/generators/ethereum`. There is no supported one-line module replacement +for other applications: owners need to review their own API and build needs. + +The migration baseline is **dev**, which is expected to land on main through +[PR #4256](https://github.com/threshold-network/keep-core/pull/4256) before this +retirement is completed. Older main still pins this fork; verify the actual +landed release rather than adding a temporary rename migration to old main. + +## Remaining consumers + +A review on 2026-09-16 found additional organization-private release/tooling +repositories with replacement directives pinning this fork's +`v1.7.1-tlabs.0` or `v1.7.1-tlabs.1`, plus operational repository inventories. +Their owners must classify each use as an active maintained build or a retained +historical snapshot. The detailed inventory is tracked privately. + +For active keep-core forks, prefer carrying forward the reviewed release +candidate's in-tree packages and generators through their normal release merge. +For independent tools, review actual imports and tests before pruning unused +requirements or choosing maintained alternatives. Historical snapshots may keep +their exact pins and checksums; deprecation is not a reason to modify recorded +release inputs. + +Default-branch code search is not an exhaustive dependency graph. Check +maintained branches, nested Go modules, build scripts, and automation before +closing the consumer review. A consumer of original Keep upstream or another +organization's fork is not automatically a consumer of this Threshold fork. + +## Retirement sequence + +The checklist and owner decisions are tracked in +[issue #33](https://github.com/threshold-network/keep-common/issues/33). + +1. Confirm the keep-core release candidate has landed on main and that neither + runtime code nor generators reacquire this external dependency. +2. Record retain/migrate decisions for every remaining maintained consumer and + historical snapshot. Validate changed consumers with their normal release + inputs and tests; record the support expectations for intentionally retained + pins. +3. Keep this repository and all tags, commits, and releases available. Do not + rename it, delete/reuse tags, hand-edit checksums, or retract valid versions + solely to announce retirement. +4. Keep CI and dependency monitoring active while the review is open. Any + maintenance release must be agreed with the affected consumer owners; new + development of the absorbed code belongs in keep-core. +5. Once the release and consumer decisions are complete, resolve outstanding + work and adjust external repository inventories/monitoring. An administrator + can then archive the repository. Archiving is separate from merging this + documentation and retains the Git contents for existing builds. + +## Go tooling and publication + +This repository contains one root Go module, including the generators; there is +no separate npm, Python, Rust, or container publication configured here. The +release workflow creates GitHub releases from `v*` tags. + +A new release is not required for this documentation notice. Because this fork +still declares the original upstream module path and consumers commonly reach +it through `replace`, do not assume that a `Deprecated:` comment here would +advertise this fork's status to every consumer of the original module. If a +Go-tool-visible notice is wanted, verify its behavior for the actual replacement +and version-selection paths and agree any final maintenance tag separately. +Do not publish a new module identity merely to deprecate it. + +References: [Go module deprecation and replacement rules](https://go.dev/ref/mod), +[GitHub archive behavior](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories). diff --git a/README.adoc b/README.adoc index 6862a75..8f32e60 100644 --- a/README.adoc +++ b/README.adoc @@ -1,12 +1,32 @@ = `keep-common` -https://github.com/keep-network/keep-common/actions/workflows/client.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/keep-common/client.yml?branch=main&event=push&label=Go build[Go build status]] +https://github.com/threshold-network/keep-common/actions/workflows/client.yml[image:https://img.shields.io/github/actions/workflow/status/threshold-network/keep-common/client.yml?branch=main&event=push&label=Go build[Go build status]] https://docs.threshold.network[image:https://img.shields.io/badge/docs-website-green.svg[Docs]] https://discord.gg/threshold[image:https://img.shields.io/badge/chat-Discord-5865f2.svg[Chat with us on Discord]] -Common libraries and tools used across Keep repositories. This repository is a -fork of https://github.com/keep-core/keep-common[`keep-core/keep-common`], -continuing independently from the upstream `v1.7.0` tag. +== Deprecation + +This standalone Threshold fork is being retired. Its runtime packages and code +generators have been incorporated into +https://github.com/threshold-network/keep-core/tree/dev[`keep-core`'s release candidate] +by https://github.com/threshold-network/keep-core/pull/4327[PR #4327]. The release +candidate no longer depends on this module, including for code generation. + +The existing repository name, Go module path, tags, and releases will be retained +for pinned builds. No `threshold-common` replacement module is planned. The +in-tree packages in `keep-core` are not a drop-in standalone replacement. + +See link:DEPRECATION.md[Deprecation plan] for release timing, remaining-consumer +review, and the conditions for archiving. CI remains active during that review. +This notice applies to the Threshold fork only, not to the separate +https://github.com/keep-network/keep-common[`keep-network/keep-common`] upstream +or other organizations' forks. + +== Background + +Common Go libraries and tools originally used across Keep repositories. This +Threshold fork preserves the upstream history through `v1.7.0` and its subsequent +fork releases. See link:RELEASE.md[Release guide] and link:CHANGELOG.md[Changelog] for versioning, tagging, and history. @@ -21,7 +41,7 @@ go test ./... == Toolchain & CI -- Go: 1.26.8 or newer (CI uses `actions/setup-go@v6` with the version from `go.mod` and module cache). +- Go: 1.26.8 or newer (CI uses `actions/setup-go@v7` with the version from `go.mod` and module cache). - Checks: `go generate` (enforced clean), `go vet`, `go build`, `go test` via `gotestsum`. - Security: `govulncheck` (blocking in CI and releases), `gosec` pinned version. - Lint: `golint` installed via `go install`. diff --git a/RELEASE.md b/RELEASE.md index 41af3ad..f761273 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,6 +1,15 @@ # Release Guide -Process for publishing tagged Go module releases for this fork of `keep-common`. +This standalone fork is being deprecated; see [DEPRECATION.md](DEPRECATION.md). +Deprecation does not require a new release. Preserve all existing tags, module +paths, and checksums so pinned consumers remain reproducible. Do not publish a +renamed module or retract otherwise valid releases as part of retirement. + +The workflow remains available for maintenance releases while consumers are +reviewed. Use the process below only for maintenance work agreed in +[the retirement tracker](https://github.com/threshold-network/keep-common/issues/33). +Do not archive the repository until that review and the release-candidate rollout +are complete. ## Versioning 1) Use SemVer tags on `main`: `vX.Y.Z` when matching upstream versions; append `-tlabs.N` for fork-only releases (increment `N` for subsequent fork tags at the same base version).