Skip to content

[UX-6] Package ecosystem is not ready for good discovery #5464

Closed

Description

@alexiscolin

📋 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.json returns 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.md documents path syntax only; effective-gno.md still 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_planned on 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, $source overview renders package info, index, functions, types, imports, files and README from JSONDocumentation
  • ✅ 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.go builds 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


Personas: #5455

Activity

  1. added
    a/uxUser experience, product, marketing community, developer experience team
    on Apr 9, 2026
  2. changed the title [-][UX] Package ecosystem has no discovery[/-] [+][UX] Package ecosystem is not ready for good discovery[/+] on Apr 9, 2026
  3. davd-gzl commented on Apr 9, 2026

    @davd-gzl
    Member

    Related: #5380

  4. changed the title [-][UX] Package ecosystem is not ready for good discovery[/-] [+][UX-6] Package ecosystem is not ready for good discovery[/+] on Apr 11, 2026
  5. notJoon commented on Apr 13, 2026

    @notJoon
    Member

    related: #1187

  6. jeronimoalbi commented on Apr 13, 2026

    @jeronimoalbi
    Contributor

    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 migration
    Nice to have

    go: integrate package discovery into gnoweb or standalone tool

  7. AmozPay commented on Apr 15, 2026

    @AmozPay
    Contributor

    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

    Image
  8. alexiscolin commented on Oct 5, 2026

    @alexiscolin
    MemberAuthor

    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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    a/uxUser experience, product, marketing community, developer experience team

    Type

    No type

    Projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions