Discuss `package.json` standardization and governance

[Ethan-Arrowood]

During the Open Source Summit NA, we heavily discussed the idea about standardizing/specifying package.json. This was in part due to interest from the WinterCG side of things; generally, how could we make it easier for other tools to adopt and support package.json for JavaScript project configuration?

I am personally looking for this groups expertise on the subjects of specification, open governance, and more as I work to try and create a solution for the above question.

[ljharb]

The most important thing to establish imo is "what are the current difficulties for other tools to adopt and support package.json for JS project configuration?". Is that laid out anywhere yet?

[Ethan-Arrowood]

I have an answer, I haven't written it down anywhere yet. I'm worried that sharing the problem without also offering some solutions will be not productive in an async format. That said, I'm confident that a problem exists.

What I'm mainly seeking to gain from this working group is guidance on standardization, specification, and governance processes.

Some loose questions we can try answering first include:

• What is the difference between using an open governance model and a standardization model?
• What is a good way to approach key stakeholders with this? (Good as in inclusive, productive, solution driven, non-accusatory, etc.)
• What, if any, intellectual property issues may we need to prepare for?
  • package.json is currently documented by multiple parties. npm's docs are unofficially considered the source of truth. Similarly with Node's additional documentation for properties such as exports.
  • Other tools also document package.json, such as Webpack's package exports section
  • Tools also have used package.json in the past for specifying configuration (Jest & ESLint)
  • Regardless of how we may actual solve specifying all of this stuff, what are some IP issues we need to be aware of?

This is all I can think of at the moment, but other's are welcome to add more questions if they'd like.

[ljharb]

My suggestion is to explicitly avoid discussing solutions of any kind until the problems are understood and agreed upon - discussing solutions prior to that, in my experience, is what's counterproductive.

[dtex]

Moddable's manifest.json might be a good case study for identifying "current difficulties." I can't say for sure that they looked at package.json and found it lacking. They may have just not been aware of it. That said, the host is quite different from what most of us are used to so it may prove to be a good litmus.

[Ethan-Arrowood]

@ljharb agreed, what I'm trying to say is that I don't expect this group to help with defining the problem itself, like answering "do we need to specify package.json or not". I'm looking for help in certain parts of that problem creation. Some aspects are also related to the solution.

Like I don't expect this group to tell me "you should create a standards body" or whatever. I'm expecting them to provide information and guidance what the pros and cons are between a standardization approach and a governance approach.

[ljharb]

Gotcha, makes sense.

[eemeli]

@Ethan-Arrowood: Like I don't expect this group to tell me "you should create a standards body" or whatever. I'm expecting them to provide information and guidance what the pros and cons are between a standardization approach and a governance approach.

Could you clarify a bit what you would expect a "standardization approach" and a "governance approach" to look like? As I understand it, a standard can help you clarify what the world looks like just now, while governance gives you a framework for changing it. For something like package.json, I would expect both of these to be of interest.

[Ethan-Arrowood]

Standardize -> Create a specification for package.json within an existing standards body such as WHATWG, or W3C, or wherever else. Development of the specification must follow the bodies existing processes. All invested parties must join the standard body. Etc...

Governance -> Using Open Governance create an group that governs the specification and its development processes.

They both are very much of interest. Specification probably is a common denominator. Standardization/Governance is another that we might not go 100% on one way or another.

[Ethan-Arrowood]

Notes from meeting:

• IP is pressing concern. Must get buy in from all contributors
• Since npm is considered a major source of truth, we should reach out to them first and get their input
• Similarly, discuss with other stakeholders and get their buy in
  • Yarn, Pnpm, Node.js, Bun, Deno
• Get buy in using endorsement from OpenJS and WinterCG
• Get buy in using personalized outreach
• Next steps: create one-pager outlining problem to be shared publicly
  • Focus on user impact
• Host discussions and collaboration in a neutral place. Maybe CPC ?

[LeaVerou]

Some thoughts, in no particular order (mentioned in the call, but dumped here for posterity):

• One of the great benefits of standardizing package.json would also be to define explicit extension points, rather than the current "anything goes" situation, where tools just add their own keys to the root.
• Standardizing in an existing consortium such as W3C (as opposed to an ad hoc group) has several benefits, such as patent policy protections, and existing recognizability and respect from a variety of stakeholders.
• Even you determine it's too early for this work to be part of a WG, there are several more lightweight arrangements for standards being incubated, such as W3C community groups, and WICG.

[jorydotcom]

Per May 30 WG meeting, removing Agenda label - @Ethan-Arrowood @tobie re-add the label when you're ready to discuss the doc again!

[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]

Here is a summary of work done so far regarding this project for folks not interested/able to join the Slack channel. For what its worth, I'll post summaries like this intermittently and I continue to encourage interested folks to join our public and archived slack channel where you can catch up on and join in on all discussions related to the project.

Without further ado, project update!

During the Open Source Summit NA 2023, OpenJS Collaborator Summit, Node.js Next-10 Technical Priorities session, a ticket was created and highly voted for stating “npm | lack of standardization/specification of package.json” is an Obstacle/Barrier for Node.js’ future success.

@Ethan-Arrowood then pursued the idea beyond the summit by creating an initial collaboration space in WinterCG (https://github.com/wintercg/proposal-package-json/issues/1). This was pivoted to a new discussion thread in OpenJS Standards WG (https://github.com/openjs-foundation/standards/issues/233), and a couple of corresponding slack threads (https://openjs-foundation.slack.com/archives/CKF0PCF54/p1684260761722349, https://openjs-foundation.slack.com/archives/CKF0PCF54/p1685494764450859, https://openjs-foundation.slack.com/archives/CKF0PCF54/p1685558255509759).

A Google Doc was created to begin drafting a "one-pager" for the purpose of gaining stakeholder buy-in. The document was to be presented to the OpenJS CPC (https://github.com/openjs-foundation/cross-project-council/issues/1082), but since the document struggled to articulate a clear “why”, we brought the discussion back to Slack to dive deeper (https://openjs-foundation.slack.com/archives/CKF0PCF54/p1685558255509759).

And that brings us to now, where a new Slack channel #package-json-discussion was created in order to continue the collaboration as we work together to define a clear goal and path forward.

Summary of the latest Slack thread, which sparked the creation of the new Slack channel:

• even tho some contributors have "why" reasons, it was agreed that they aren't strong enough yet
• there are concerns about impacting the status-quo. i.e. what would motivate npm and Node.js to relinquish "control" of package.json to another party
• another solution was presented: create a centralized ecosystem-wide doc site for package.json. This helps solve some of the fragmentation problem that Ethan has mentioned without having npm or node to lose control
• collaboratively we determined to refactor the google doc to present problems more clearly, expand stakeholder section, and remove any presentation of a solution. The document should simply encourage stakeholders to buy-in to working together towards any solution.
• it was stated that working on smaller pieces first may be significantly more achievable. We could take pieces of package.json and specify/standardize them, then work to get npm/node/everyone-else to conform to those new standards within existing systems, and slowly iterate from there. Maybe eventually the entirety of package.json will be standardized in that way, maybe this will let project implement package.json alternatives. For example, if we can truly standardize SemVer, then npm can be certain to conform to that spec for package.json, while all other runtimes and package managers can too regardless if their project configuration file is called package.json or not.

Thank you for reading through all of this. Did my best to summarize while including important details. Again, if this work interests you, please join us in the OpenJS Slack channel #package-json-discussion . I will also personally be attending OpenJS standards and CPC WG meetings to continue providing status updates on the work and asking for feedback from other WG members.

🚀

[DerekNonGeneric]

Strongly support the effort. Thanks for the summary, and the shared experience not only of mine but evidently the rest of the previous Node.js Loaders team members, shows that this effort would necessitate cross-project collaboration even btwx rivals (so-called) like Node and Deno as was evident last time a serious proposal was made to undertake such an effort (or at least something quite similar).

Refs: https://github.com/nodejs/loaders/issues/52