Open kgryte opened 10 months ago
@Planeshifter Given your previous efforts to build scaffolding tooling, would be good to get your opinion on the above proposal and what, if any, additional structured information might be useful.
@Planeshifter Pinging you here, in case you have forgotten about this issue.
@kgryte is this in the works?
@Snehil-Shah Sort of. We've created a Google sheet for collecting this information, but that effort has stalled. Something like this would be rather useful, but it involves a fair amount of manual labor, and we haven't had the bandwidth to push forward.
Opening up a tracking issue for this one should help us move forward with since it does require a good number of additions to be made. Should we open one ?
From what I gather resolving this will help in the scaffolding process of both the Gsheets project and developing C implementations, right ?
@adityacodes30 Before opening up a tracking issue, we need to settle on the desired path forward. But, yes, this is also relevant to the scaffolding process for both GSheets and the C implementation work.
Generally, I think we should start with math/base/special
, the second priority would be blas/ext/base
. But this is as pertains to Gsheets. Would have to see what the community thinks
My my main concern, and it is for me a serious one, is that this increases duplication of package documentation even more, which is already quite excessive. If we undertake this, I think it's necessary to at the same time build tooling (either LLM-assisted or just deterministic) that scaffolds out the required other files such as repl.txt
. There is a trap that this will be decently easy to add for existing packages but then cause an additional burden when trying to add new packages. I feel we have encountered this several times in the past so we should have a good answer to address this concern.
As for the proposed schema, it seems sensible. I would drop keywords
and extra_keywords
and instead follow the previously discussed approach of excluding all boilerplate keywords from the keywords
array of the package.json
in the development repo and then populate them during the release process.
Here are my answers to the raised questions:
What other data, if any, should be included?
Not sure. Maybe something for testing. Should it support options
object definitions?
One open question is whether we should include support for constraints? E.g., in the arcsine PDF function a < b. In the example JSON, I've simply manually adjusted the PRNG parameters and the example values to ensure we don't run afoul of that constraint. It was not clear to me how we might include such constraints in a universal way which is machine parseable and actionable in scaffolding tools.
This is a pretty deep rabbit hole and not something that should be encoded in metadata, I think. Burden would be on the person populating the metadata to make sure any constraints are satisfied.
Which other package namespaces might benefit from structured meta data and how would their schemas differ from the examples above?
Probably most that have base
implementations and those that need package variants that operate on ndarray
s and strided arrays. So stats/base/dists
, string
, etc. But keeping scope limited and not branching out to all kinds of packages seems prudent.
The proposal above suggests adding the meta data to package.json files. This could lead to bloat in the package.json files. Another possibility is putting such info in a separate .stdlibrc file in the root package directory. Would this be preferrable?
In my view, bloat will not be an issue. Metadata would be stripped when publishing packages, so this would only affect the development environment. package.json
is familiar to folks as source of package metadata, and easily loadable as JSON. Custom file would be unfamiliar to developers.
Re: extra keywords. The point here is that there are keywords which are universal for a particular conceptual function and which should be included in all downstream scaffolded packages, and others which are not universal and which scaffolding tool may, or may not, be interested in using.
increases duplication of package documentation even more...this will be decently easy to add for existing packages but then cause an additional burden when trying to add new packages.
I don't have a simple answer here. To me, it is a balance of trade-offs. Right now, the situation is not tenable, as we need to individually define example ranges, aliases, etc, for all higher order packages (e.g., strided, iter, ndarray), which vastly outweighs the maintenance and creation burden if we bite the bullet when creating a base package in the first place.
Description
This RFC proposes adding structured package data to facilitate automation and scaffolding.
Overview
The need for structured package data has been discussed at various points during stdlib development. This need has become more paramount when seeking to automate specialized package generation for packages which wrap "base" packages for use with other data structures. The most prominent example being
math/base/special/*
APIs which are wrapped to generate a variety of higher-order packages, includingmath/iter
math/strided
math/
generics supporting ndarrays, arrays, and scalarsand more recently in work exposing those APIs in spreadsheet contexts. In each context, one needs to
and in some contexts
While various attempts have been made to automate scaffolding of higher-order packages, where possible, each attempt has relied on manual entry of necessary scaffold data, including parameter names, descriptions, and example values. To date, we have not created a centralized database from which we pull desired package meta data.
Proposal
In this RFC, I propose adding structured meta data to "base" packages. This structured meta data can then be used in various automation contexts, most prominent of which is automated scaffolding.
The meta data would be stored as JSON in a subfield of the
__stdlib__
configuration object ofpackage.json
files. The choice of JSON stems from the ability to use JSON Schema for validation and linting.Examples
I've included two examples below.
math/base/ops/add:
stats/base/dists/arcsine/pdf:
Annotated Overview
Discussion
Related Issues
No.
Questions
a < b
. In the example JSON, I've simply manually adjusted the PRNG parameters and the example values to ensure we don't run afoul of that constraint. It was not clear to me how we might include such constraints in a universal way which is machine parseable and actionable in scaffolding tools.package.json
files. This could lead to bloat in thepackage.json
files. Another possibility is putting such info in a separate.stdlibrc
file in the root package directory. Would this be preferrable?Other
No.
cc @Planeshifter
Checklist
RFC:
.