Skip to content

Commit c62b51a

Browse files
mhdawsonmhdawson
committed
doc: add initial doc for consumers
Signed-off-by: Michael Dawson <[email protected]>
1 parent 4a64b0e commit c62b51a

File tree

2 files changed

+256
-20
lines changed

2 files changed

+256
-20
lines changed

‎README.md

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -23,28 +23,34 @@ The spec proposal is currently being reviewed and is open for feedback. As we h
2323
finalized the documentation, this package is similarly in draft. Until the spec is
2424
considered complete I will hold off on publishing `1.0.0`.
2525

26-
## Usage
26+
## Command line usage
27+
28+
A command line tool is provided which supports the following commands:
29+
30+
* show - show the support info for the package tree.
31+
* validate - validate support info for a package, to be used by a
32+
maintainer before publishing.
33+
34+
These commands support the following options:
35+
36+
* --canonical - prefer canonical data over package support data
37+
that may be available locally. Default is `false`.
38+
* --fetch - if local support data is not available or --canonical
39+
is specified, fetch the support data from the remote canonical
40+
location when needed. Default is `false`
41+
* --base-path - directory root within which the tool can read/validate
42+
package support files. The default is the directory from which the
43+
package.json for the top level package was read.
44+
45+
More details and explanation of the use cases for these
46+
commands is provided in [command line usage](./doc/command-line-usage.md).
47+
48+
The simplest way to run the tool is to simply run:
2749

2850
```
29-
$ npm i @pkgjs/support
51+
npx support show
3052
```
3153

32-
```javascript
33-
const support = require('@pkgjs/support')
34-
35-
// Load in a projects package.json
36-
const pkgJson = require('./package.json')
37-
38-
// The current spec says that the "support" key will
39-
// be an object with the support schema
40-
try {
41-
support.validate(pkgJson.support)
42-
} catch (e) {
43-
// Validation failure
44-
// The error is annotated with the
45-
// errors and schema from `ajv`
46-
console.error(e)
47-
console.log(e.validationErrors)
48-
console.log(e.validationSchema)
49-
}
54+
```
55+
npx support validate
5056
```

‎doc/command-line-usage.md

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# Using the packge support tool from the command line
2+
3+
There are 2 main uses cases for the package support tool
4+
5+
* Package Maintainers - document and communicate expectations to consumers
6+
* Package Consumers - understand more about their key dependencies and where they
7+
should invest.
8+
9+
The sections which follow document the usage/options of interest for each use
10+
case.
11+
12+
Once you have node.js installed (version 10.x or later) you can
13+
run the support command directly using npx or optionally npm install the
14+
package and add the `bin` directory to your path. In either case
15+
you can run the support tool using `npx support`.
16+
17+
## Package Consumers
18+
19+
The support tool helps package conumers review and understand the
20+
package support information provided by maintainers. See
21+
[Package-support.md](https://github.com/nodejs/package-maintenance/blob/master/docs/PACKAGE-SUPPORT.md)
22+
which documents the suggested best practice and the specific format of the
23+
package support information.
24+
25+
Package consumers use the `show` command to display the support information
26+
provided by package maintainers.
27+
28+
It is understood that this is only the most basic support that can be provided
29+
to the consumer. The current focus for the support tool is to provide features
30+
to encourage/support maintainers to add the package support info to their packages.
31+
In the future more advanced options can be added to the show command to provide
32+
more deduplicated or focussed views of the information available.
33+
34+
The general flow is:
35+
36+
* install the package to display package support information
37+
* cd into the directory which contains the root package
38+
* execute `npx support show`
39+
40+
For example once node.js and the package support tool are installed to show
41+
the package support for a module (the support module itself in this example):
42+
43+
```shell
44+
npm install support
45+
cd node_modules/support
46+
npx support show
47+
```
48+
49+
with a stripped down version of the the output to make it more easily readable being:
50+
51+
```shell
52+
@pkgjs/support(0.0.2) - { "versions": [ { "version": "*", "target": { "node": "supported" }, "response": { "type": "best-effort" }, "backing": { "hobby": "https://github.com/pkgjs/support" } } ] }
53+
@npmcli/arborist(0.0.0) - unknown
54+
@npmcli/installed-package-contents(1.0.5) - unknown
55+
npm-bundled(1.1.1) - unknown
56+
npm-normalize-package-bin(1.0.1) - unknown
57+
@npmcli/map-workspaces(0.0.0-pre.1) - unknown
58+
glob(7.1.6) - unknown
59+
fs.realpath(1.0.0) - unknown
60+
inflight(1.0.6) - unknown
61+
wrappy(1.0.2) - unknown
62+
63+
...
64+
65+
y18n(4.0.0) - unknown
66+
yargs-parser(18.1.3) - unknown
67+
camelcase(5.3.1) - unknown
68+
```
69+
70+
The command shows the support information for the tree of packages starting from the package being assessed.
71+
In this case it ONLY shows support info for the `support` package as the support information has not
72+
been added to any of the dependent packages yet.
73+
74+
The support info shown is:
75+
76+
```shell
77+
@pkgjs/support(0.0.2) - { "versions": [ { "version": "*", "target": { "node": "supported" }, "response": { "type": "best-effort" }, "backing": { "hobby": "https://github.com/pkgjs/support" } } ] }
78+
```
79+
80+
For the rest of the modules it simply shows `unknown` as the packages do not yet provide it.
81+
82+
The package support tool prefers support information which is available locally within the package after installation.
83+
This is to allow offline use. The documented best practices for adding support info are written to maximize
84+
the likelyhood that at reasonably up to date copy of the support information is provided as part of the npm
85+
install.
86+
87+
If the consumer wishes to ignore the local information and always use the canonical version of the support information
88+
they can add the `--canonical` option to the command. Instead of using the local support info, if available, it will
89+
display the URL from which the canonical information can be retrieved. This is the same behavior when
90+
as when the package.json specifies that there is support info but it is not available in the npm package itself.
91+
92+
For example:
93+
94+
```
95+
npx show --canonical
96+
```
97+
98+
99+
```
100+
@pkgjs/support(0.0.2) - https://github.com/pkgjs/support/blob/master/package-support.json
101+
@npmcli/arborist(0.0.0) - unknown
102+
@npmcli/installed-package-contents(1.0.5) - unknown
103+
npm-bundled(1.1.1) - unknown
104+
npm-normalize-package-bin(1.0.1) - unknown
105+
@npmcli/map-workspaces(0.0.0-pre.1) - unknown
106+
glob(7.1.6) - unknown
107+
fs.realpath(1.0.0) - unknown
108+
inflight(1.0.6) - unknown
109+
wrappy(1.0.2) - unknown
110+
111+
...
112+
113+
y18n(4.0.0) - unknown
114+
yargs-parser(18.1.3) - unknown
115+
camelcase(5.3.1) - unknown
116+
```
117+
118+
where the support info is listed as
119+
`https://github.com/pkgjs/support/blob/master/package-support.json`
120+
121+
The --canonical option does not automatically pull the remote information so that the
122+
consumer can choose to find the locations without automatically triggering a number of
123+
remote calls.
124+
125+
If the consumer wants to have the canonical information pulled automatically they can
126+
add the `--fetch` option which will pull the remote support information when necesarry.
127+
128+
129+
The following command/options will always show the most up to date package support information
130+
at the cost of fetching from remote sites.
131+
```
132+
npx show --canonical --fetch
133+
```
134+
135+
`--fetch` can also be used without `--canonical` in which case the remote support
136+
information will only be pulled when it is not provided as part of the npm package.
137+
138+
Local support information may be available locally but outside of the package itself.
139+
This may be the case if you are using mono-repo and sharing the support file.
140+
In this case, by default, the support tool will not read/display files outside of the
141+
packge itself to avoid potential security issues. In order to allow the tool to display
142+
support info in these cases you can use the `--base-path` option to specify the top
143+
most root from which packge support files can be read:
144+
145+
```shell
146+
npx support --base-path=${cwd}/../.. show
147+
```
148+
149+
In the case where the required base path is not specified, and the file is outside
150+
of the package, the tool will simply print the url from which the support information
151+
can be obtained versus displaying it. For example:
152+
153+
```
154+
@pkgjs/support-show-local-escape-ok(0.0.1) - https://github.com/pkgjs/support/blob/master/my-support-info.json
155+
```
156+
157+
where the `support` entry was:
158+
159+
```json
160+
"support": "../../fixtures/my-support-info.json",
161+
```
162+
163+
## Package Maintainers
164+
165+
Package maintainers want to add and manage the support information for their modules.
166+
167+
Ultimately we'll want commands help generate the support info, but as a first step
168+
the `validate` command is provided which validates that the info is in the
169+
right format/locations.
170+
171+
To add support information a maintainer needs to:
172+
173+
* add information to the package.json which specifies were to find the support info
174+
* provide a file with the package support info.
175+
176+
The `validate` command checks that both the information added to the package.json
177+
and the file containing the support info (package-support.json by default) is valid.
178+
179+
180+
[Integration into package.json](https://github.com/nodejs/package-maintenance/blob/master/docs/PACKAGE-SUPPORT.md#integration-into-packagejson)
181+
explains the options for providing support info and what goes into the package.json for
182+
each case.
183+
184+
`npx suport validate` is run from the directory that contains the package.json for the package.
185+
Depending the how the `support` section in the package.json is configured validate will:
186+
187+
* validate the format of the `support` section in the package.json conforms to the
188+
documentation in [Integration into package.json](https://github.com/nodejs/package-maintenance/blob/master/docs/PACKAGE-SUPPORT.md#integration-into-packagejson)
189+
* calculate the file which cotains the support info
190+
* if the file is available locally, use that data unless the `--canonical`
191+
option was specified.
192+
* if the file is not available locally or `--canonical` was specified
193+
* if --fetch was provided as an option, fetch the file and use that data
194+
* otherwise simply print that the file was not resolved and the url from
195+
where it can be retrieved.
196+
197+
If both the entry in the package.json and the contents of the file with the package support
198+
information is validate you'll see the follwowing output:
199+
200+
```shell
201+
Your support information is valid!
202+
```
203+
204+
If the support information is not avialable locally or you have specified
205+
`--canonical` without `--fetch` you'll see something like:
206+
207+
```shell
208+
support info not resolved: https://github.com/pkgjs/support/blob/master/package-support.json
209+
```
210+
211+
in this case the file is local to the package, but --canonical was specified. The same
212+
would be shown if the info in the package.json file pointed to a file a different github
213+
respository.
214+
215+
You might also see this if the file with the support information is outside of the
216+
the package itself, but still available locally. This may be the case if you
217+
are using mono-repo and sharing the support file. An example would be:
218+
219+
```json
220+
"support": "../../fixtures/my-support-info.json",
221+
```
222+
223+
This is the case because, by default, the support tool will not read/display files outside of the
224+
packge itself in order to avoid potential security issues. In order to allow the tool to validate
225+
support info in these cases you can use the `--base-path` option to specify the top
226+
most root from which packge support files can be read:
227+
228+
```shell
229+
npx support --base-path=${cwd}/../.. validate
230+
```

0 commit comments

Comments
 (0)