Present package.json standardization document

[Ethan-Arrowood]

Originally discussed with Standards WG (openjs-foundation/standards#233), I am driving an initiative to standardize a package.json specification. During that call we created a loose plan for how to get buy-in from all necessary stakeholders. The ask was for me to author (and others collaborate) a one pager style document outlining the problem and solution. Once complete, this document would be presented to the CPC for endorsement consideration. With the OpenJS Foundation's formal endorsement, I will then reach out to necessary stakeholders and begin the formation of an OpenJS Core Working Group to further the development of the project.

This issue is a request to present a completed draft of the document to the CPC at the June 6th meeting for finalization and endorsement consideration.

🚀

[mcollina]

I would recommend you to open an issue to the Node.js TSC repo as well, I think you might want to get buy-in for this work by Node.js as first-thing.

[tobie]

Heads-up that I won't make our June 6 call.

While I really love the energy behind this project, it's still not clear to me at this point what problem this standardization effort would want to solve. Imho, this needs work before being presented to the CPC. Right now, it still feels like a solution (standardizing package.json) in search of a problem. The doc needs a clear set of problem statements and use cases. This is probably going to require substantial research, reaching out to the different stakeholders and conducting interviews with them.

As described in a comment in the doc, problem statements should look something like this:

[PROBLEM DESCRIPTION] has led to [IMPACT]. A resolution would entail [REQUIREMENTS].

For example (I'm making this up):

Conflicts in package.json property names has led to X medium to high CVEs in 2022, Y of which had known exploits. A resolution would entail agreeing on a set of property names and their meanings, a name space system, and a registry mechanism.

Uses case descriptions should look somewhat like this:

To enable [USE CASE DESCRIPTION], we must overcome [CURRENT LIMITATIONS]. Successfully implementing this would lead to [EXPECTED BENEFITS]. The requirements for this involve [REQUIREMENTS].

For example (I'm also making this up):

To enable defining dependencies hosted elsewhere than on Github, we must overcome the absence of a namespace solution for defining shorthand dependencies. Successfully implementing this would lead to a richer ecosystem of providers and less of a monoculture around hosting software. The requirements for this involve defining an easy syntax to namespace dependencies and managing GitHub being a legacy default.

This will get you the combination of:

1. Understanding precisely what it is you're trying to solve (and thus hopefully getting others interested about solving it too).
2. Clarifying precisely what the requirements would be.
3. Making it easy to do a cost/benefit analysis (cost of implementing requirements / benefits of enabling the use cases and catering to the problems), thus allowing everyone to clearly decide for themselves that this is indeed worth their while.

---

While I do agree that providing a space for folks to come together to work on such a document would make sense, I'm not seeing key stakeholders express a shared sense of urgency that this is a problem worth solving yet. Demonstrating that shared sense of urgency is what's missing here, imho. It needs to happen (through collecting compelling use cases and problem statements) before this is taken to the next step.

That said, while I don't see compelling value in creating a more formalized structure around this work just quite yet, I won't object if others in the community see this differently.

[Ethan-Arrowood]

Based on some comments on slack as well as the document, I may no longer present this on June 6th. I'll be sure to follow up on this thread as soon as possible as things change.

Sounds good @mcollina - Node.js is definitely a key stakeholder we want involved from the get go. I think we are still getting things organized though. I'll be sure to reach out to the TSC when it is most appropriate.

Thank you @tobie too. These thoughts are very valuable. Lets chat on the slack thread and iterate from there.

[Ethan-Arrowood]

If folks are interested in the continuation of this work, please join us in the #package-json-discussion channel in the OpenJS Slack workspace.

[Ethan-Arrowood]

last week we determined a different direction for this work. We are going to focus on a bottom-up (standardizing pieces of package.json) approach rather than a top-down (standardizing all of package.json). Furthermore, with one of the major concerns being developer experience, we are going to simultaneously start trying to improve that by creating a research hub. This hub will be a collection of documentation (and potentially some high level summary) of all of the various package.json fields we see in the wild. I will be contributing the start of that research hub this week.

Reminder to join us in the OpenJS Slack channel for latest updates

[ovflowd]

Reminder to join us in the OpenJS Slack channel for latest updates

Any specific channel?

[Ethan-Arrowood]

https://openjs-foundation.slack.com/archives/C05AWQH5E4R

#improve-package-json