Skip to content

Latest commit

 

History

History
172 lines (140 loc) · 12.7 KB

adr-114-undo-109.md

File metadata and controls

172 lines (140 loc) · 12.7 KB
Raw

ADR 114: Partly Undo ADR 109 (Reduce Go API Surface)

Changelog

  • 2024-04-25: First draft (@adizere)

Status

Accepted (PR #2897)

Context

In ADR 109 we have decided to internalize numerous Go APIs following the research and due diligence in that ADR. This will take effect with CometBFT v1 release.

Prior to releasing v1 RC, we have found that our diligence was insufficient and several Go modules that we internalize with ADR 109 would either (i) force a difficult upgrade on users or, worse, would (ii) provoke some users to fork CometBFT.

The question in the present ADR is how to deal with the potential damage our internalized APIs will create on users' codebases.

Alternative Approaches

The following alternative approaches were considered.

  1. Do nothing. This approach will make the upgrade to v1 very difficult and potentially lead to new forks of Comet.
  2. Fully undo ADR 109. This approach will minimize disruption with v1 release, but will bring the CometBFT codebase into a state prior to the implementation of that ADR, i.e., if we do breaking changes in non-critical modules that will require major version bumps, which will encourage stagnation and slow uptake of new releases.

Decision

We will partly undo ADR 109, by selectively re-exporting (i.e., make public) certain modules. For modules state and store, we have made them public (#2610) because this blocked the SDK upgrade to CometBFT v1.

To select additional modules that we will make public (again) we will follow this high-level strategy:

  1. Identify all /internal modules that are being imported by open-source projects using a tool such as https://www.sourcegraph.com/search.
  2. For each of these modules, categorize them by importance. There are 3 levels: high, medium, low. By 'importance' we mean "important for current or later modularization work in CometBFT."
  3. For modules that have high importance, we will:
    1. make the public,
    2. mark the module as deprecated,
    3. establish communication with the team(s) using that module to find a way in v2 to make the package internal again with minimal user disruption.
  4. For modules with medium importance, we will:
    1. make them public,
    2. mark them as deprecated; the rationale is that these modules being public is unlikely to block us in the future, and if we find they do block us, we will internalize them in v2 and follow the same approach as for high importance.
  5. For modules with low importance, we will:
    1. If there is no project using that module, then we keep it private, as decided in ADR 109.
    2. If there are projects using the module, then there are two sub-cases to consider:
      • i) If the APIs in that module contain Comet-specific features, then we'll make the module public; the rationale is that otherwise we would encourage users to fork Comet.
      • ii) If the APIs in that module comprise general-purpose features, then keep the module private; the rationale is that such modules have replacements and users will find it easy to replace them (e.g. rand number generation, file manipulation, synchronization primitives).

We will present these decisions to the community call, and we will err on the side of exposing more (i.e., making public) rather than retaining modules as private when there is ambiguity around the decision for a certain module.

Detailed Design

Module Inventory

The following table contains our research, categorization by importance, and decision for each module in the current internal -- as of v1.0.0-alpha.2 -- directory of CometBFT.

Column legend:

  • Comet internal module name: The name of the module
  • Decision: The decision we are taking (either make public, or keep private) for this module
  • # Repositories affected (non-forks): Count of how many public, open-source projects we have identified that are using APIs from this module
  • Affected files: How many files (among the affected repositories, both forks and non-forks) would be affected if we make this module private; this is rough measure of the impact -- or "damage" -- of making the module private
  • Importance: Our assessment of how important is it that we make this module (eventually) private
  • URL: The public source of data we have used to research the data in this table
Comet internal module name Decision # Repositories affected (non-forks) Affected files Importance URL
timer keep private 0 7 low timer-url
progressbar keep private 0 4 low progressbar-url
inspect keep private 0 0 low inspect-url
fail keep private 0 10 low fail-url
events keep private 0 10 low events-url
cmap keep private 0 10 low cmap-url
autofile keep private 0 10 low autofile-url
async keep private 0 8 low async-url
flowrate keep private 0 10 low flowrate-url
bits keep private 0 26 low bits-url
blocksync keep private 0 6 low blocksync-url
clist keep private 0 24 low clist-url
indexer keep private 0 0 low indexer-url
net keep private 1 40 low net-url
statesync 🧹 make public 1 16 medium statesync-url
evidence keep private 1 26 high evidence-url
consensus keep private 1 64 high consensus-url
protoio 🧹 make public 3 44 low protoio-url
sync 🧹 make public 3 172 low sync-url
tempfile keep private 4 16 low tempfile-url
strings keep private 4 14 low strings-url
service 🧹 make public 6 156 low service-url
os keep private 7 262 low os-url
rand keep private 7 317 low rand-url
pubsub 🧹 make public 7 169 medium pubsub-url

Remarks on the table

For evidence and consensus: There is a single project we have identified using APIs from these modules, specifically https://github.com/forbole/juno. The maintainers of this project have agreed it is not a problem for them if we keep the two modules private.

Summary

To summarize, these modules will remain public in v1 and marked as deprecated:

  • statesync
  • protoio
  • sync
  • service
  • pubsub

For these four modules which are becoming private in v1, we need to be extra-careful by helping users transition to other general-purpose libraries:

  • tempfile
  • strings
  • os
  • rand

Consequences

Positive

  • A smaller, more manageable Go API surface area.
  • Less aggressive progression towards the goals set out in ADR 109.

Negative

  • Some power users may experience breakages. If absolutely necessary, certain packages can be moved back out of the internal directory in subsequent minor releases.