├── README.md ├── devengines-field-proposal.md └── meeting-notes ├── 2023-10-03.md ├── 2023-11-07.md ├── 2024-01-02.md ├── 2024-02-06.md └── 2024-03-05.md /README.md: -------------------------------------------------------------------------------- 1 | # package-metadata-interoperability-collab-space 2 | 3 | The goal of the Package Metadata Interoperability Collab Space is to improve how JavaScript developers define their packages across the ecosystem. The group is currently working to better understand package.json and how developers use it to define their projects. 4 | 5 | ## Current Initiatives 6 | 7 | 1. [package.json research](https://github.com/openjs-foundation/package-json-research) 8 | 1. This initiative's goal is to research existing usage of `package.json` throughout the JavaScript ecosystem. 9 | 2. With this research, the group can develop tooling, documentation, specifications, and much more. 10 | 3. The linked repository contains all information for how to get involved and contribute. 11 | 2. [`@pkgjs/create-pkg` tooling](https://github.com/pkgjs/create-pkg) 12 | 1. An initiative originally created by Node.js collaborators for Node.js based package tooling, the efforts here are now being expanded to align with this group's wider scope. 13 | 2. The tooling being developed will be package manager and runtime agnostic and help developers across the entire JavaScript ecosystem. 14 | 3. [`devEngines` field proposal](https://github.com/openjs-foundation/package-metadata-interoperability-collab-space/issues/15) 15 | 1. The `devEngines` field was proposed as a partial solution to the ongoing Node.js and Corepack debate. 16 | 2. The intent is for this field to provide all relevant development environment information akin to the existing `engines` field. -------------------------------------------------------------------------------- /devengines-field-proposal.md: -------------------------------------------------------------------------------- 1 | # Proposal: `package.json` `devEngines` Field 2 | 3 | This is a specification a `package.json` field to define the runtime and package manager for _developing_ a project or package (_not_ consuming/installing it as a dependency in another project). The field is named `devEngines` and is a new top-level field defined with this schema: 4 | 5 | ```typescript 6 | interface DevEngines { 7 | os?: DevEngineDependency | DevEngineDependency[]; 8 | cpu?: DevEngineDependency | DevEngineDependency[]; 9 | libc?: DevEngineDependency | DevEngineDependency[]; 10 | runtime?: DevEngineDependency | DevEngineDependency[]; 11 | packageManager?: DevEngineDependency | DevEngineDependency[]; 12 | } 13 | 14 | interface DevEngineDependency { 15 | name: string; 16 | version?: string; 17 | onFail?: 'ignore' | 'warn' | 'error' | 'download'; 18 | } 19 | ``` 20 | 21 | The `os`, `cpu`, `libc`, `runtime`, and `packageManager` sub-fields could either be an object or an array of objects, if the user wants to define multiple acceptable OSes, CPUs, C compilers, runtimes or package managers. The first acceptable option would be used, and `onFail` would be triggered for the last defined option if none validate. If unspecified, `onFail` defaults to `error` for the non-array notation; or it defaults to `error` for the last element in the array and `ignore` for all prior elements, for the array notation. Validation would check the name and version ranges. 22 | 23 | The `name` field would be a string, corresponding to different sources depending on the parent field: 24 | 25 | - `os`: [NPM docs for `engines.os`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#os). 26 | - `cpu`: [NPM docs for `engines.cpu`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#cpu). 27 | - `libc`: `glibc` or `musl`; see [NPM docs for `config.libc`](https://docs.npmjs.com/cli/v10/using-npm/config#libc). 28 | - `runtime`: [WinterCG Runtime Keys](https://runtime-keys.proposal.wintercg.org/). 29 | - `packageManager` . . . I don’t know, we could define the list as part of the spec, or perhaps it would need to correspond to an npm registry package name. Suggestions welcome. 30 | 31 | The `version` field syntax would match that defined for [`engines.node`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines), so something like `">= 16.0.0 < 22"` or `">= 20"`. If unspecified, any version matches. 32 | 33 | The `onFail` field defines what should happen if validation fails: 34 | 35 | - `ignore`: nothing. 36 | - `warn`: print something and continue. 37 | - `error`: print something and exit. 38 | - `download`: remediate the validation failure by downloading the requested tool/version. 39 | 40 | In the event of `onFail: 'download'`, it would be the responsibility of the tool to determine what and how to download, perhaps by looking in the tool’s associated lockfile for a specific version and integrity hash. It could also be supported on a case-by-case basis, like perhaps Yarn and pnpm could support downloading a satisfactory version while npm would error. 41 | 42 | ## Examples 43 | 44 | ### Typical example 45 | 46 | ```json 47 | "devEngines": { 48 | "runtime": { 49 | "name": "node", 50 | "version": ">= 20.0.0", 51 | "onFail": "error" 52 | }, 53 | "packageManager": { 54 | "name": "yarn", 55 | "version": "3.2.3", 56 | "onFail": "download" 57 | } 58 | } 59 | ``` 60 | 61 | ### “Uses every possible field” example: 62 | 63 | ```json 64 | "devEngines": { 65 | "os": { 66 | "name": "darwin", 67 | "version": ">= 23.0.0" 68 | }, 69 | "cpu": [ 70 | { 71 | "name": "arm" 72 | }, { 73 | "name": "x86" 74 | } 75 | ], 76 | "libc": { 77 | "name": "glibc" 78 | }, 79 | "runtime": [ 80 | { 81 | "name": "bun", 82 | "version": ">= 1.0.0", 83 | "onFail": "ignore" 84 | }, 85 | { 86 | "name": "node", 87 | "version": ">= 20.0.0", 88 | "onFail": "error" 89 | }, 90 | ], 91 | "packageManager": [ 92 | { 93 | "name": "bun", 94 | "version": ">= 1.0.0", 95 | "onFail": "ignore" 96 | }, 97 | { 98 | "name": "yarn", 99 | "version": "3.2.3", 100 | "onFail": "download" 101 | } 102 | ] 103 | } 104 | ``` 105 | 106 | ## Future Expansions 107 | 108 | Some potential future expansions of this spec that have been discussed are: 109 | 110 | - `runtime` and `packageManager` might take shorthand string values defining the desired name or name with version/version range. 111 | 112 | ## References 113 | 114 | - Inspiration: https://github.com/nodejs/node/issues/51888#issuecomment-1967102442 115 | 116 | - Initial discussion: https://github.com/openjs-foundation/package-metadata-interoperability-collab-space/issues/15 117 | 118 | ## Implementations 119 | 120 | - https://github.com/npm/npm-install-checks/pull/116 121 | 122 | - https://github.com/npm/cli/pull/7766 123 | -------------------------------------------------------------------------------- /meeting-notes/2023-10-03.md: -------------------------------------------------------------------------------- 1 | # Meeting 2023-10-03 2 | 3 | ## Attendees: 4 | 5 | - Ethan Arrowood (@Ethan-Arrowood) 6 | - Luke Karrys 7 | - Robin Ginn 8 | - Darcy Clarke 9 | - Claudio Wunder 10 | 11 | ## Agenda: 12 | 13 | - Welcome to the newest OpenJS Foundation Collab Space 🎉 14 | - What is this group's goal? - Open collaboration space for all JavaScript developers focussed on package metadata 15 | - Node.js Package Maintenance Group overlap and differentiation 16 | - Mandate: Identify key projects in Node ecosystem and find ways to help them become sustainable 17 | - Overlap: package.json documentation, common-keys, tooling 18 | - Project Update: package.json research: https://github.com/openjs-foundation/package-json-research 19 | - To Review: https://github.com/openjs-foundation/package-json-research/pull/3 20 | - Some links from Darcy: 21 | - https://github.com/npm/validate-npm-package-name 22 | - https://github.blog/changelog/2023-09-27-block-npm-package-publishes-when-names-and-versions-dont-match-between-manifest-and-tarball-package-json/ 23 | - https://github.com/npm/npm-package-arg 24 | - To Review: https://github.com/openjs-foundation/package-json-research/pull/7 25 | - Create a pull request / issue template 26 | - Project Update: create-package-json 27 | - https://github.com/pkgjs/create-package-json/pull/33 28 | - https://github.com/pkgjs/create/issues/7 29 | 30 | ## Action Items: 31 | 32 | - Social Media announcement 33 | - Blog post 34 | - Keep key stakeholders in mind - personalized outreach 35 | - Add current projects to main README 36 | - pkgjs create and create-package-json ownership/licensing 37 | - "Michael Dawson"-bot for meeting management 38 | - Alternative time slots 39 | -------------------------------------------------------------------------------- /meeting-notes/2023-11-07.md: -------------------------------------------------------------------------------- 1 | # Meeting 2023-11-07 2 | 3 | ## Attendees: 4 | - Ethan Arrowood (@Ethan-Arrowood) 5 | - Rick Markins (@rxmarbles) 6 | - Luke Karrys (@lukekarrys) 7 | - Wes Todd ( @wesleytodd) 8 | 9 | ## Agenda: 10 | - Review previous meeting notes: https://github.com/openjs-foundation/package-metadata-interoperability-collab-space/blob/main/meeting-notes/2023-10-03.md 11 | - Created some issues from previous action item so they don’t get missed again 12 | - pkgjs create and create-package-json ownership/licensing 13 | - Adopt a monorepo 14 | - `npm` adoption of create-package-json 15 | - We created some issues: https://github.com/pkgjs/create-pkg/issues 16 | -------------------------------------------------------------------------------- /meeting-notes/2024-01-02.md: -------------------------------------------------------------------------------- 1 | Jan 2, 2024 - OpenJS Package Metadata Interop Collab Space 2 | 3 | ### Attendees: 4 | 5 | - Ethan Arrowood (@Ethan-Arrowood) 6 | - Robin Ginn (@rginn) 7 | - Wes Todd (@wesleytodd) 8 | - Darcy Clarke (@darcyclarke) 9 | - Luke Karrys (@lukekarrys) 10 | 11 | ### Notes: 12 | 13 | - package.json research 14 | - Repo: https://github.com/openjs-foundation/package-json-research 15 | - PR: https://github.com/openjs-foundation/package-json-research/pull/7 16 | - Need to include “use cases” or “implementation details” based on npm registry. 17 | - Careful of implicit bias - keep language open and present details as facts not suggestions. 18 | - For example: https://docs.npmjs.com/cli/v10/using-npm/scope#associating-a-scope-with-a-registry 19 | - Discussion: documenting use cases in package.json field research 20 | - Maybe just document how npm works, invite yarn/bun want to add their docs if they can 21 | - Repo for adjusting package.json info: https://github.com/npm/normalize-package-data 22 | - This is a legacy package 23 | - All package.json manip for npm has moved to https://github.com/npm/package-json 24 | - Finish automating meeting generating: https://github.com/nodejs/create-node-meeting-artifacts/pull/144 25 | - How can we be more actionable? 26 | - Many libraries exist for working with package.json 27 | - https://github.com/npm/normalize-package-data 28 | - https://github.com/npm/types 29 | - https://github.com/npm/package-json 30 | - https://github.com/npm/read-package-json-fast 31 | - https://github.com/npm/read-package-json 32 | - https://www.npmjs.com/package/@types/npm 33 | - Tool as main function of the work = @pkgjs/create-pkg 34 | - **pkgjs** 35 | - Disagree and commit - who cares if we use monorepo or not. Whoever is doing the work, make a tooling decision and lets ship it 36 | - Question at hand, there are two repos atm: create-pkg, and create-package-json, can they be combined into one project? 37 | - https://github.com/pkgjs/create-pkg 38 | - https://github.com/pkgjs/create-package-json 39 | - Can we close out stale issues/prs? 40 | - What work do we need to do next? 41 | 42 | ### Action items: 43 | 44 | - [ ] Begin opening draft PRs for keys you are researching: https://github.com/openjs-foundation/package-json-research/pull/ 45 | - [ ] @Ethan-Arrowood to update and merge research prs. Begin working on more fields as well 46 | - [ ] @wesleytodd to “move the needle” on pkgjs create-pkg work 47 | - [ ] Robin work with Ethan on a blog with our comms folks 48 | -------------------------------------------------------------------------------- /meeting-notes/2024-02-06.md: -------------------------------------------------------------------------------- 1 | Jan 2, 2024 - OpenJS Package Metadata Interop Collab Space 2 | 3 | ### Attendees: 4 | 5 | - Ethan Arrowood (@Ethan-Arrowood) 6 | - Wes Todd (@wesleytodd) 7 | - Darcy Clarke (@darcyclarke) 8 | - Luke Karrys (@lukekarrys) 9 | - Rick Markins (@rxmarbles) 10 | - Ruy Adorno (@ruyadorno) 11 | 12 | ### Notes: 13 | 14 | > Summary written after-the-fact as no notes were taken during the meeting 15 | 16 | - Blog post was released! 17 | - https://openjsf.org/blog/package-metadata-interoperability-collab-space-intro 18 | - Research: 19 | - PR https://github.com/openjs-foundation/package-json-research/pull/8 was merged 20 | - Tooling: 21 | - PR https://github.com/pkgjs/create-pkg/pull/18 progress 22 | - Do we want a session at upcoming Collab Summit (April @ London) 23 | 24 | ### Action items: 25 | 26 | - If collab summit is approved, @wesleytodd to lead session 27 | - @Ethan-Arrowood to finally finish https://github.com/openjs-foundation/package-json-research/pull/3 28 | - @rxmarbles to finish https://github.com/pkgjs/create-pkg/pull/18 -------------------------------------------------------------------------------- /meeting-notes/2024-03-05.md: -------------------------------------------------------------------------------- 1 | # Package Meta Interop Collab Space 2 | 3 | ## Attendees 4 | 5 | * Rick Markins (@rxmarbles) 6 | * Jordan Harband (@ljharb) 7 | * Ethan Arrowood (@Ethan-Arrowood) 8 | * Luke Karrys (@lukekarrys) 9 | * Geoffrey Booth (@GeoffreyBooth) 10 | * Darcy Clarke (@darcyclarke) 11 | * Robin Ginn (@rginn) 12 | * Wes Todd (@wesleytodd) 13 | * Steven (@styfle) 14 | * Trivikram Kamat (@trivikr) 15 | 16 | ## Agenda 17 | 18 | * `devEngines` proposal 19 | 20 | ## `devEngines` proposal 21 | 22 | * Presented in [#15](https://github.com/openjs-foundation/package-metadata-interoperability-collab-space/issues/15) 23 | * @darcylarke has concerns on adding a third field and has given a more verbose explaination in [npm cli #7253](https://github.com/npm/cli/pull/7253#issuecomment-1965846137) 24 | * @ljharb still feels this should be added regardless of it being a top level field or not, just due to functionality being applied 25 | * @wes ??? (accurate) 26 | * @darcyclarke engines are currently supported to various degrees by all package managers and should be leveraged because it has overlapping capabilities of the newly proposed devEngines 27 | * @lukekarrys concerns of repurposing something that used to mean one thing that would mean somthing else that can confuse end users 28 | * @darcy linked to npm's own docs on [engines](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines) and showed examples of each package managers respecting engines and erroring if the wrong engines.$package-manager is used 29 | * @geoffrey how would using engines to specify package manager stop other package managers from being run? it could only specify all managers as top level keys in engines 30 | * @wesleytodd specifying two ways (packageManager and devEngines) to do the same thing is a mistake and should make a hard break in favor of a single way to do something 31 | * @styfle prefers `packageManager` but `devEngines` could work too - more interested in what happens when this field is defined and what tool will actually download the package manager? corepack? something else? 32 | ## Representation 33 | 34 | * @ethanarrowood Need more representation from other stakeholders involved to help with this effort 35 | * Was commented that possibly timezones being an issue 36 | 37 | ## Notes 38 | --------------------------------------------------------------------------------