RFC - Package metadata

[moul]

At some points, we'll want to attach metadata to packages.

Right now, I can see three categories of metadata:

• source related: version, isForkOf, parentVersion, gitRepo, gitSha, contact, etc
• publication related: publicationDate, publishedBy, publicationParameters, publicationPath, etc
• dynamic: isLatest, isDeprecated, etc

This issue is to discuss the what, how, and when.

---

What

What metadata is useful/useless?

What should be required/optional, and what could be sane default values?

How

Should we add a package.json or equivalent?

Should we extend gno.mod?

Should we use idiomatic go with comments?

Should we make the metadata callable from another contract?

Should we rely on indexers to make the magic and keep the chain minimalist?

When

As soon as we know where we're going, let's try to find the best first step and, ideally, a stakeholder that would require the feature.

[moul]

First opinion:

• What: nothing mandatory; structure inspired by package and repo references: npm and github
• How: idiomatic go, with machine-friendly comments.
• When: probably when addressing Contributing policies for adding/updating new stdlibs packages #239, versioning, licensing/forks.

[irclausen]

For "What" maybe the following adds

• publication/dynamic (could be either): and equivalent to Weekly Downloads (executions or # of realms using the package), something to indicate how widely used a package may be. (This is helpful sometimes in choosing between similar packages or to find other projects that reference a package for reference)(This could also give some insight into packages may become a target as an attack vector and drive some auditing priority)
• source/publication: License (unless all packages are subject to the same licensing by design)

Will the convention be to keep all the documentation/readme information for a package on GitHub as the source of truth? Otherwise perhaps that should be captured as well.

[yassinouider]

Idiomatic go is the best for me.

You can just add on top of the package or in separate file a comment note like it is done for BUG etc in the doc.

MARKER(uid): note body

// Package example is an example package.
//
// GNO(publicationDate): xxx
// GNO(publishedBy): yyy
// GNO(publicationPath): zzz
package example

[thehowl]

The way I see it we should extend gno.mod, but really only adding what is absolutely necessary, and as far as I can see there is not really a lot of metadata which I personally would consider useful. I think that because gno doesn't follow the go principle of import path = repository (by requesting the HTTPS page with ?go-get=1 to get the meta-tags for non-exceptions), there should be an extension in gno mod to add source information:

source [vcs] [repo-root] [sha-or-version]

We could potentially restrict vcs to just git, but it allows us to change it in the future should it be necessary. But the specification I think should be pretty identical to that of the go-import meta tag, without the import-prefix and with the version/sha added at the end (this last one in the same format as other versions/shas in go.mod).

Most importantly this means that we can have the default behaviour for gnokey maketx addpkg that of modifying the gno.mod being uploaded to have the latest source information (gathering data from the git repository, ie. putting the upstream of the current branch OR origin if not set, and the tag or sha matching the current HEAD)

As for the other tags, I think they are either potentially harmful or redundant (we should include what is important for machine tools to parse - and avoid information which can be obtained by some other more canonical way, as otherwise the package author has to keep the data in sync).

• gitRepo, gitSha, version would be addressed by source
• isForkOf: not really important, one could still very easily lie and this is more useful as README information
• parentVersion - ?
• contact - better to keep out, avoiding scrapers harvesting data off packages?
• publicationDate - better if is actually more "objective" (based on git tag/commit)
• publishedBy - redundant with git author
• publicationParameters - don't know what would be here, maybe case where the data would be useful?
• publicationPath - is this not implicitly the module path?
• isLatest - better to determine this comparing current version with what is available on the git
• isDeprecated - I think the infamous chokidar message is a good example of why this is not a good idea:
  Chokidar 2 does not receive security updates since 2019. Upgrade to chokidar 3 with 15x fewer dependencies
  But in any case, for completeness, I think that deprecation is something better suited for the README and/or documentation (often because I think we should also discourage deprecating entire packages rather than individual functions)

[thehowl]

Do we still want this?

I don't think we want this.

[leohhhn]

We will want to have some metadata for packages shown in gnoweb2.

Question is, will this data be parsed directly from the chain, or in some other way?
cc @alexiscolin, @gfanton WDYT?