docs: added target lib naming convention ADR #237
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR introduces an Architecture Decision Record (ADR) documenting the naming convention strategy for AlgoKit libraries across multiple programming languages. The decision proposes transitioning from the current "utils" naming pattern to an "SDK" naming pattern to better reflect the comprehensive nature of these libraries.
Key changes:
- Creates ADR 0001 documenting the package naming strategy decision
- Updates the decisions README to include reference to the new ADR
- Establishes naming conventions for six target languages (TypeScript, Python, Go, Kotlin, Swift, Rust)
Reviewed Changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/book/decisions/README.md | Adds entry for new package naming strategy ADR |
| docs/book/decisions/0001-package-naming-strategy.md | Complete ADR documenting the naming convention decision and rationale |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
lempira
force-pushed
the
docs/target-lib-naming-adr
branch
from
ee77b30 to
885b49f
Compare
lempira
force-pushed
the
docs/target-lib-naming-adr
branch
from
885b49f to
6fe7484
Compare
| - Strong AlgoKit brand association | ||
| - Language designation still clear | ||
|
|
||
| **Cons:** |
There was a problem hiding this comment.
Does this also have the similar cons with algokit-sdk-{lang} as well, i.e. this is a breaking change?
| - "Utils" implies limited utility functions rather than full SDK capabilities | ||
| - Inconsistent with the evolving AlgoKit ecosystem strategy | ||
|
|
||
| ### 2. Adopt SDK naming: `algokit-sdk-{lang}` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
| - 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 |
There was a problem hiding this comment.
| - 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.
| - "Utils" implies limited utility functions rather than full SDK capabilities | ||
| - Inconsistent with the evolving AlgoKit ecosystem strategy | ||
|
|
||
| ### 2. Adopt SDK naming: `algokit-sdk-{lang}` |
There was a problem hiding this comment.
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?
| **Pros:** | ||
| - No breaking changes required | ||
| - Existing users familiar with naming | ||
| - No migration effort needed |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
ADR for the target lib package naming convention