diff --git a/README.md b/README.md index 5526d9d84a..f53bc628a3 100644 --- a/README.md +++ b/README.md @@ -269,10 +269,16 @@ If the module you're referencing is an ambient module (uses `declare module`, or #### I notice some packages having a `package.json` here. -Usually you won't need this. When publishing a package we will normally automatically create a `package.json` for it. -A `package.json` may be included for the sake of specifying dependencies. Here's an [example](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json). -We do not allow other fields, such as `"description"`, to be defined manually. -Also, if you need to reference an older version of typings, you must do that by adding `"dependencies": { "@types/foo": "x.y.z" }` to the package.json. +Usually you won't need this. +Definitely Typed's package publisher creates a `package.json` for packages with no dependencies outside Definitely Typed. +A `package.json` may be included to specify dependencies that are not other `@types` packages. +[Pikaday is a good example.](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json) +Even if you write your own `package.json`, you can only specify dependencies; other fields such as `"description"` are not allowed. +You also need to add the dependency to [the list of allowed packages](https://github.com/microsoft/types-publisher/blob/master/dependenciesWhitelist.txt). +This list is updated by a human, which gives us the chance to make sure that `@types` packages don't depend on malicious packages. + +In the rare case that an `@types` package is deleted and removed in favor of types shipped by the source package AND you need to depend on the old, removed `@types` package, you can add a dependency on an `@types` package. +Be sure to explain this when adding to the list of allowed packages so that the human maintainer knows what is happening. #### Some packages have no `tslint.json`, and some `tsconfig.json` are missing `"noImplicitAny": true`, `"noImplicitThis": true`, or `"strictNullChecks": true`.