Skip to content

docs: added target lib naming convention ADR #237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+112 −1
Open

docs: added target lib naming convention ADR #237

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ wheelhouse/

# AI artifacts
CLAUDE.local.md
.claude/settings.local.json
.claude/
AGENTS.md
.tasks/
.opencode/
Expand Down
110 changes: 110 additions & 0 deletions docs/book/decisions/0001-package-naming-strategy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
status: proposed
date: 2025-08-20
decision-makers: Bruno Martins, Larkin Young, Joe Polny, David Rojas
consulted: [TBD]
---

# Package Naming Strategy for Multi-Language AlgoKit Libraries

## Context and Problem Statement

The AlgoKit ecosystem currently includes utilities libraries named `algokit-utils-ts` and `algokit-utils-py` for TypeScript and Python respectively. As we expand to support additional languages (Go, Kotlin, Swift, and Rust) and evolve these libraries into more comprehensive SDKs, we need to establish a consistent naming strategy.

The current "utils" naming was adopted due to naming conflicts with `algosdk` packages published by Algorand Technologies. However, these libraries have evolved beyond simple utilities and now provide comprehensive SDK functionality for Algorand development.

## Decision Drivers

- Clear and consistent naming across all target languages
- Reflect the true nature of these libraries as SDKs rather than utility collections
- Avoid naming conflicts with existing Algorand packages
- Follow language-specific naming conventions
- Enable easy discovery and understanding of package purpose

## Target Languages

- TypeScript (ts)
- Python (py)
- Go (go)
- Kotlin (kt)
- Swift (swift)
- Rust (rs)

## Considered Options

### 1. Keep current naming: `algokit-utils-{lang}`

Continue using the existing naming pattern:
- `algokit-utils-ts` (TypeScript)
- `algokit-utils-py` (Python)
- `algokit-utils-go` (Go)
- `algokit-utils-kt` (Kotlin)
- `algokit-utils-swift` (Swift)
- `algokit-utils-rs` (Rust)

**Pros:**
- No breaking changes required
- Existing users familiar with naming
- No migration effort needed
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be noted there will be migration effort because we break compatibility with SDK. I would imagine there are legacy codebases out there that use both algosdk and utils. I think the fact that migration is inevitable to some degree makes it a pro for SDK because it allows gradual migration. A codebase can use both utils in old code paths and the core SDK in new code paths.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A codebase can use both utils in old code paths and the core SDK in new code paths.

We could also do something similar without having another package by adding a new namespace to the existing utils package which contains the core SDK.


**Cons:**
- Misrepresents the true nature of these comprehensive SDKs
- "Utils" implies limited utility functions rather than full SDK capabilities
- Inconsistent with the evolving AlgoKit ecosystem strategy

### 2. Adopt SDK naming: `algokit-sdk-{lang}`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this name the most for the reasons stated in the pros list. An advantage of moving away from the name algokit-utils-ts is that it decouples the 2 packages and make migration easier. Taking lora as an example. It has algokit-utils-ts and algokit-subscriber as dependencies. If we release a new version algokit-utils-ts without upgrading algokit-subscriber, this could cause package conflicts. However, if we release algokit-sdk-ts, the user can point to algokit-sdk-ts and they can still use the old algokit-subscriber if they need to.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'd likely be releasing algokit-utils-ts as a breaking change, in which case the package manager should handle any package conflict issues as algokit-subscriber-ts would be depending on the previous version. Am I missing something?


Use SDK naming to reflect the true nature of these libraries:
- `algokit-sdk-ts` (TypeScript)
- `algokit-sdk-py` (Python)
- `algokit-sdk-go` (Go)
- `algokit-sdk-kt` (Kotlin)
- `algokit-sdk-swift` (Swift)
- `algokit-sdk-rs` (Rust)

**Language-specific adaptations:**
- **TypeScript/JavaScript**: `@algorandfoundation/algokit-sdk-ts` (scoped package)
- **Python**: `algokit_sdk_py` (snake_case following PEP conventions)
- **Swift**: `AlgoKitSDKSwift` (PascalCase following Swift conventions)
- **Kotlin**: `algokit-sdk-kt` (kebab-case following Kotlin/Java conventions)
- **Go**: `algokit-sdk-go` (kebab-case for module names)
- **Rust**: `algokit_sdk_rs` (snake_case following Rust conventions)

**Pros:**
- Accurately reflects comprehensive SDK functionality
- Clear indication of purpose for developers
- Consistent naming strategy across all languages
- Better discoverability and understanding
- Avoids conflicts with existing algosdk packages
- Follows established conventions in each language ecosystem

**Cons:**
- Breaking change requiring migration from existing packages
- Requires documentation updates and migration guides
- Temporary confusion during transition period
- Migration coordination needed with major version releases
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Migration coordination needed with major version releases
- Migration coordination needed with major version releases
- Two parallel codebases need to be supported during the migration period

This means we'll have duplicate code and need to manage changes between the codebases until the repo is archived.


### 3. Use AlgoKit branding: `algokit-{lang}`

Simplified naming without SDK/utils designation:
- `algokit-ts` (TypeScript)
- `algokit-py` (Python)
- `algokit-go` (Go)
- `algokit-kt` (Kotlin)
- `algokit-swift` (Swift)
- `algokit-rs` (Rust)

**Pros:**
- Clean, simple naming
- Strong AlgoKit brand association
- Language designation still clear

**Cons:**
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this also have the similar cons with algokit-sdk-{lang} as well, i.e. this is a breaking change?

- Doesn't indicate the nature of the package (SDK vs CLI vs other tools)
- Potential confusion with other AlgoKit packages
- Less descriptive than SDK naming
- May conflict with future AlgoKit packages

## Decision Outcome

_TO BE DECIDED_
1 change: 1 addition & 0 deletions docs/book/decisions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ This section contains Architecture Decision Records documenting important decisi
## Contents

- **[0000: Native Implementations vs FFI](./0000-native-implementations-vs-ffi.md)** - Decision on implementation strategy for multi-language support
- **[0001: Package Naming Strategy](./0001-package-naming-strategy.md)** - Decision on naming convention for multi-language AlgoKit libraries

## ADR Format

Expand Down
Loading