Repository navigation
Description
📋 Part of the onboarding audit brainstorm. Status sync 2026-09-15: no longer blocked, and three of its seven items have shipped. Discovery is done; versioning is the remaining work.
Journey stage: BUILD → USE
Persona impact: A (Go Dev), B (Web3 Vet), D (CTO), E (OSS Contributor)
Problem
Composability is one of Gno's strongest technical differentiators: every on-chain package can be imported by any realm. But two gaps undermine this promise:
1. No way to discover existing on-chain packages
Go developers are used to pkg.go.dev. Rust developers have crates.io. Gno has no equivalent. Developers must browse gnoweb manually by namespace or ask on Discord. Duplicate packages get created because existing ones aren't findable.
Team feedback (@jeronimoalbi ): "A good index of useful and documented on-chain packages that devs could easily find."
🔄 2026-09-15: largely addressed. #5761 shipped an omnibar search (
handler_search.go,realm_directory.go,controller-searchbar.ts),gno.land/search.jsonreturns 200, and/r/and/p/are browsable indexes.
2. No documented patterns for versioning or upgrading realms
Experienced developers immediately ask: How do I version my realm? How do I upgrade deployed code? What's the state migration pattern? GitHub issues #2743 and #1838 explored several approaches; both are now closed (2025-03-31 and 2024-11-15) without anything being documented for builders.
Team feedback (@jeronimoalbi ): "I didn't see good indication on versioning patterns, which is one of the first things good devs will ask themselves."
🔄 2026-09-15: still true and now the bulk of this issue.
gno-packages.mddocuments path syntax only;effective-gno.mdstill carries a TODO listing "versioning" and "upgrade pattern" as unwritten.
Evidence
- GnoScan exists as a blockchain explorer but not as a package registry
- ~~Compare: ~10 gno.land apps~~ — mainnet now serves 64 realms and 127 packages (
gno.land/search.json) - Compare: OpenZeppelin upgrade guide (Solidity), CosmWasm migration docs
The first two original bullets (no searchable index, no auto-generated docs) are resolved and now live under Action items.
Impact
Composability is unusable if developers can't discover what's available. CTOs (Persona D) who can't answer "how do we upgrade?" won't commit a team. Web3 vets (Persona B) without familiar upgrade patterns question production-readiness.
Action items
🔄 Status sync 2026-09-15: the old closing note told readers not to start until #3518 landed. #3518 was closed
not_plannedon 2026-04-15 and discovery shipped without it. Note removed.
Shipped:
- ✅ searchable web UI for on-chain packages — feat(gnoweb): add omnibar search for realms, packages and users #5761 MERGED 2026-06-05, omnibar +
/search.json+/r//p/indexes, live on mainnet. Remaining gaps vs pkg.go.dev: no ranking, no cross-package symbol search. (Pagination is capped at 1000 server-side, but the chain exposes 191 paths today, so it is not yet a real limit) - ✅ auto-generated docs from on-chain source code — feat(gnoweb): add package overview source doc #5572 MERGED 2026-07-10,
$sourceoverview renders package info, index, functions, types, imports, files and README fromJSONDocumentation - ✅ integrate package discovery into gnoweb — same as above, shipped in gnoweb rather than as a standalone tool
Open, and no longer blocked:
- "Imported by" count to surface popular packages — not started.
components/overview_imports.gobuilds outbound imports only; no reverse index exists anywhere in the repo - 🟡 document how realm paths work with versions — partial.
resources/gno-packages.md§"Version Suffixes" documents the syntax (…/v1, at most one suffix) but says nothing about when to bump, how callers migrate, or state handoff - publish upgrade strategies (new path vs. in-place) with code examples — not started. The only adjacent sentence in the docs is
resources/configuring-gno-projects.md:58: "It can be re-uploaded - the new version fully overwrites the old one." - comparison with Solidity proxy pattern and CosmWasm migration — not started.
r/docs/soliditypatterns/covers banker, counter, ownable, reentrancy and statelock, is quarantined so undeployed, and omits proxy and migration entirely
Related work
- Gno Realm and Ownership Spec #2743, Gno Realm and Ownership Spec (closed)
- Proposal: Implementing Versioning Across Application Serialization Structures #1838, Proposal: Implementing Versioning Across Application Serialization Structures (closed)
- META Gnoweb improvements #1187, META Gnoweb improvements, umbrella tracker (still open)
-
Realm/package registry & query overhaul #3518, Realm/package registry & query overhaul— CLOSEDnot_planned2026-04-15, abandoned. This was named as the prerequisite for the whole issue; it was abandoned and discovery shipped without it -
feat(examples): upgradeable #4816,— CLOSED unmerged 2026-06-04, the upgrade-pattern exploration did not landfeat(examples): upgradeable - feat(gnovm): add
vm/qlatestversionquery and soft version warnings for gnokey addpkg #5380, soft version warnings forgnokey addpkg(still open)
Personas: #5455
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
[-][UX] Package ecosystem has no discovery[/-][+][UX] Package ecosystem is not ready for good discovery[/+]davd-gzl commentedon Apr 9, 2026
Related: #5380
[-][UX] Package ecosystem is not ready for good discovery[/-][+][UX-6] Package ecosystem is not ready for good discovery[/+]notJoon commentedon Apr 13, 2026
related: #1187
jeronimoalbi commentedon Apr 13, 2026
Opinion on action items:
go: searchable web UI for on-chain packages (à la pkg.go.dev)
It would be very useful to have category support.
Maybe packages should be added explicitly either on-chain or off-chain, instead of being indexed from TXs.
go: auto-generated docs from on-chain source code
go: "Imported by" count to surface popular packages
go: document how realm paths work with versions
go: publish upgrade strategies (new path vs. in-place) with code examples
no-go: comparison with Solidity proxy pattern and CosmWasm migrationNice to have
go: integrate package discovery into gnoweb or standalone tool
AmozPay commentedon Apr 15, 2026
I think it would be good to add a keyword system for packages and realms so published packages would be discoverable by topics, e.g.
dao,oracle,grc20,utils...example with npmjs.org
feat(gnoweb): add omnibar search for realms, packages and users (#5761)
alexiscolin commentedon Oct 5, 2026
Closing. Package search (#5761) and generated docs (#5572) shipped, and Explore (#6273) builds on them. Versioning docs are in #6000. "Imported by" can get its own issue if someone picks it up.
Overview: #6280