casraf/DefinitelyTyped
1
0
Fork 0
mirror of https://github.com/chenasraf/DefinitelyTyped.git synced 2026-05-18 01:49:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

[README] Create a package.json section (#49686)

Browse Source 
* [README] Create a package.json section

* Apply suggestions from code review

Co-authored-by: Piotr Błażejewicz (Peter Blazejewicz) <peterblazejewicz@users.noreply.github.com>

Co-authored-by: Piotr Błażejewicz (Peter Blazejewicz) <peterblazejewicz@users.noreply.github.com>
This commit is contained in:
Jack Bates
2020-12-03 10:07:00 -07:00
committed by GitHub
parent 6812d6fbb0
commit b94b68318f
6 changed files with 215 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
README.cn.md
View File

@@ -20,9 +20,10 @@
- [创建一个新的包](#创建一个新的包)
- [常见错误](#常见错误)
- [删除一个包](#删除一个包)
- [Linter](#linter)
- [\<my package>-tests.ts](#my-package-teststs)
- [验证](#验证)
- [\<my package>-tests.ts](#my-package-teststs)
- [Linter](#linter)
- [package.json](#packagejson)
</details>
- [Definition Owners](#definition-owners)
* [FAQ](#faq)
@@ -222,7 +223,7 @@ Definitely Typed 的成员会定期查看新的 PRs，但是请记住当有许
Definitely Typed 中其他引用了删除包的任何包，都需要去更新去引用新的捆绑类型。
你可以查看 `npm test` 中的错误来获得此列表。
添加一个带有 `"dependencies": { "foo": "x.y.z" }` 的 `package.json` 文件，去修复这些错误。
添加一个带有 `"dependencies": { "foo": "x.y.z" }` 的 [`package.json`](#packagejson) 文件，去修复这些错误。
比如：
```json
@@ -238,27 +239,10 @@ Definitely Typed 中其他引用了删除包的任何包，都需要去更新去
如果这个包从未发布到 Definitely Typed 过，则不需要将其添加到 `notNeededPackages.json`.
#### Linter
#### 验证
所有新的包都必须通过 lint. 需要添加 `tslint.json` 文件去 lint 这个包。
```js
{
"extends": "dtslint/dt.json"
}
```
这应该是一个已完成项目里 `tslint.json` 文件的唯一内容。如果这个文件关闭了某些规则，是因为它还未完全修复。例如：
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(若要使某个 lint 规则不生效，可以使用 `// tslint:disable rule-name`，当然使用 `//tslint:disable-next-line rule-name` 更好。)
通过运行 `npm test <package to test>` 去测试你的改动，其中 `<package to test>` 是你的包名。
这个脚本使用了 [dtslint](https://github.com/Microsoft/dtslint).
#### \<my package>-tests.ts
@@ -309,10 +293,41 @@ f("one");
你可以查阅 [dtslint](https://github.com/Microsoft/dtslint#write-tests) 的 readme 去看更多详细信息。
#### 验证
#### Linter
通过运行 `npm test <package to test>` 去测试你的改动，其中 `<package to test>` 是你的包名。
这个脚本使用了 [dtslint](https://github.com/Microsoft/dtslint).
所有新的包都必须通过 lint. 需要添加 `tslint.json` 文件去 lint 这个包。
```js
{
"extends": "dtslint/dt.json"
}
```
这应该是一个已完成项目里 `tslint.json` 文件的唯一内容。如果这个文件关闭了某些规则，是因为它还未完全修复。例如：
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(若要使某个 lint 规则不生效，可以使用 `// tslint:disable rule-name`，当然使用 `// tslint:disable-next-line rule-name` 更好。)
#### package.json
通常你不需要它。
Definitely Typed 包的发布者会为在 Definitely Typed 之外没有依赖的包创建一个 `package.json` 文件。
`package.json` 包含了指定的而不是其他 `@types` 包的依赖。
当你发布包的时候会自动创建一个 `package.json` 的文件。
[Pikaday 是一个好的例子](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)。
包含 `package.json` 以便解析依赖。这有个 [示例](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)。
你还需要将依赖项添加到[允许的包列表](https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.txt)。
即使你编写自己的 `package.json` 文件，也只能指定依赖项。不允许使用其他字段，例如 `"description"`.
该列表是人为更新，这让我们确保了 `@types` 包不会依赖恶意包。
在极少数情况下，`@types` 包会被删除，而不是源码包中提供的类型，并且你需要依赖旧的已经删除的 `@types` 包，你可以添加对 `@types` 包的依赖。
再添加到允许的包列表中时，请确保作出解释，以便让人工维护者知道发生了什么。
### Definition Owners
@@ -354,20 +369,6 @@ NPM 包应该会在几分钟内更新。如果已经超过了一小时，请在
如果你引用的外部模块（使用 `export`），那么请使用导入。
如果你引用的是环境模块（使用 `declare module`, 或者只声明全局变量），那么请使用 `<reference types="" />`.
#### 我注意带这里有一些包含 `package.json` 的包。
通常你不需要它。
Definitely Typed 包的发布者会为在 Definitely Typed 之外没有依赖的包创建一个 `package.json` 文件。
`package.json` 包含了指定的而不是其他 `@types` 包的依赖。
当你发布包的时候会自动创建一个 `package.json` 的文件。
[Pikaday 是一个好的例子](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)。
包含 `package.json` 以便解析依赖。这有个 [示例](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)。
你还需要将依赖项添加到[允许的包列表](https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.txt)。
即使你编写自己的 `package.json` 文件，也只能指定依赖项。不允许使用其他字段，例如 `"description"`.
该列表是人为更新，这让我们确保了 `@types` 包不会依赖恶意包。
在极少数情况下，`@types` 包会被删除，而不是源码包中提供的类型，并且你需要依赖旧的已经删除的 `@types` 包，你可以添加对 `@types` 包的依赖。
再添加到允许的包列表中时，请确保作出解释，以便让人工维护者知道发生了什么。
#### 有些包没有 `tslint.json` 文件，有些 `tsconfig.json` 文件缺少 `"noImplicitAny": true`, `"noImplicitThis": true`, 或 `"strictNullChecks": true`.
当然它们是错误的，你可以通过发起 PR 来修复它们。

58
README.es.md
View File

@@ -15,9 +15,10 @@ Vea también el sitio web [definitelytyped.org](http://definitelytyped.org), aun
- [Crear un nuevo paquete](#crear-un-nuevo-paquete)
- [Errores comunes](#errores-comunes)
- [Remover un paquete](#remover-un-paquete)
- [Lint](#lint)
- [\<my package>-tests.ts](#my-package-teststs)
- [Running Tests](#running-tests)
- [\<my package>-tests.ts](#my-package-teststs)
- [Lint](#lint)
- [package.json](#packagejson)
</details>
- [Definition Owners](#definition-owners)
* [FAQ](#faq)
@@ -209,27 +210,14 @@ Se puede remover ejecutando `npm run not-needed -- typingsPackageName asOfVersio
- `asOfVersion`: Un stub será publicado a `@types/foo` con esta versión. Debería ser más grande que cualquier versión publicada actualmente.
- `libraryName`: Un nombre descriptivo de la librería, p.ej. "Angular 2" en vez de "angular2". (Si es omitido, será idéntico a "typingsPackageName".)
Cualquier otro paquete en Definitely Typed que referencie el paquete eliminado deberá ser actualizado para referenciar los tipos bundled. para hacer esto, añade `package.json` con `"dependencies": { "foo": "x.y.z" }`.
Cualquier otro paquete en Definitely Typed que referencie el paquete eliminado deberá ser actualizado para referenciar los tipos bundled. para hacer esto, [añade `package.json`](#packagejson) con `"dependencies": { "foo": "x.y.z" }`.
Si un paquete nunca estuvo en Definitely Typed, no será necesario añadirlo a `notNeededPackages.json`.
#### Running Tests
#### Lint
Para realizar el lint a un paquete, solo añade `tslint.json` al paquete que contiene `{ "extends": "dtslint/dt.json" }`. Todos los paquetes nuevos deberán pasar por el proceso de linted.
Si el `tslint.json` deshabilita algunas reglas esto se debe a que aún no se ha acomodado. Por ejemplo:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(Para indicar que la regla lint realmente no es utilizada, usa `// tslint:disable rule-name` o mejor, `//tslint:disable-next-line rule-name`.)
Realiza una prueba ejecutando `npm test <package to test>` donde `<package to test>` es el nombre de tu paquete.
Este script utiliza [dtslint](https://github.com/Microsoft/dtslint).
#### \<my package>-tests.ts
@@ -280,10 +268,29 @@ f("one");
Para más detalles, vea el [dtslint](https://github.com/Microsoft/dtslint#write-tests) readme.
#### Running Tests
#### Lint
Realiza una prueba ejecutando `npm test <package to test>` donde `<package to test>` es el nombre de tu paquete.
Este script utiliza [dtslint](https://github.com/Microsoft/dtslint).
Para realizar el lint a un paquete, solo añade `tslint.json` al paquete que contiene `{ "extends": "dtslint/dt.json" }`. Todos los paquetes nuevos deberán pasar por el proceso de linted.
Si el `tslint.json` deshabilita algunas reglas esto se debe a que aún no se ha acomodado. Por ejemplo:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(Para indicar que la regla lint realmente no es utilizada, usa `// tslint:disable rule-name` o mejor, `// tslint:disable-next-line rule-name`.)
#### package.json
Normalmente no lo necesitarás. Cuando publicas un paquete normalmente nosotros automáticamente crearemos un `package.json` para eso.
Un `package.json` puede ser incluido por el bien de especificar dependencias. Aquí tienen un [ejemplo](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json).
No aceptamos otros campos, tales como `"description"`, para que sean definidos manualmente.
Además, si necesitas referencia a una versión anterior de typings, debes hacerlo añadiendo `"dependencies": { "@types/foo": "x.y.z" }` al package.json.
### Definition Owners
@@ -325,13 +332,6 @@ Los paquetes NPM deberán ser actualizados en unas cuantas horas. Si ha pasado m
Si el módulo al cual te estás refiriendo es un módulo externo (utiliza `export`), utilice una import.
Si el módulo al cual te refieres es un módulo ambiente (utiliza `declare module`, o simplemente declara las globales), utilice `<reference types="" />`.
#### He notado que algunos paquetes aquí tienen `package.json`.
Normalmente no lo necesitarás. Cuando publicas un paquete normalmente nosotros automáticamente crearemos un `package.json` para eso.
Un `package.json` puede ser incluido por el bien de especificar dependencias. Aquí tienen un [ejemplo](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json).
No aceptamos otros campos, tales como `"description"`, para que sean definidos manualmente.
Además, si necesitas referencia a una versión anterior de typings, debes hacerlo añadiendo `"dependencies": { "@types/foo": "x.y.z" }` al package.json.
#### Algunos paquetes no tienen `tslint.json`, y algunos `tsconfig.json` no contienen `"noImplicitAny": true`, `"noImplicitThis": true`, o `"strictNullChecks": true`.
Entonces están equivocados. Puedes ayudar enviando un pull request para arreglarlos.

56
README.ko.md
View File

@@ -18,9 +18,10 @@
- [새 패키지를 만들기](#새-패키지를-만들기)
- [많이 저지르는 실수들](#많이-저지르는-실수들)
- [패키지 삭제하기](#패키지-삭제하기)
- [린터](#린터)
- [\<my package>-tests.ts](#my-package-teststs)
- [검증하기](#검증하기)
- [\<my package>-tests.ts](#my-package-teststs)
- [린터](#린터)
- [package.json](#packagejson)
</details>
- [Definition Owners](#definition-owners)
* [자주 하는 질문들](#자주-하는-질문들)
@@ -233,27 +234,15 @@ Definitely Typed 의 관리자들이 주기적으로 새로운 풀 리퀘스트(
- `asOfVersion` 는 새 스텁(Stub) 용 `@types/foo` 를 퍼블리시(Publish)할 버전입니다. 이 버전은 현재 NPM 에 올라간 버전보다 더 높은 버전이어야 합니다.
- `libraryName` 는 패키지의 이름을 읽기 쉽게 쓴 것입니다. 즉, "angular2" 대신에 "Angular 2" 와 같이 쓰는 것이 좋습니다. (생략했을 경우에는 "typingsPackageName" 와 같은 것으로 취급됩니다.)
Definitely Typed 의 다른 패키지들이 삭제된 자료형(Typing) 패키지를 사용하고 있을 경우, 형(Type)을 포함하기 시작한 원래 패키지를 사용하도록 수정해야합니다. 삭제된 자료형(Typing) 패키지를 사용하는 각 Definitely Typed 패키지들의 `package.json` 파일에 `"dependencies": { "foo": "x.y.z" }` 를 추가해주시면 됩니다.
Definitely Typed 의 다른 패키지들이 삭제된 자료형(Typing) 패키지를 사용하고 있을 경우, 형(Type)을 포함하기 시작한 원래 패키지를 사용하도록 수정해야합니다. 삭제된 자료형(Typing) 패키지를 사용하는 각 Definitely Typed 패키지들의 [`package.json`](#packagejson) 파일에 `"dependencies": { "foo": "x.y.z" }` 를 추가해주시면 됩니다.
Definitely Typed 에 한 번도 올라온 적 없는 패키지가 형(Type)을 포함하게 되었다면, `notNeededPackages.json` 파일에 추가할 필요도 없습니다.
#### 검증하기
#### 린터
`npm test <package to test>` 명령을 통해 변경점을 테스트할 수 있습니다. 이 때, `<package to test>`은 테스트하고 싶은 패키지의 이름입니다.
자료형(Typing) 패키지를 린트(Lint)하려면, 패키지 디렉토리에 `{ "extends": "dtslint/dt.json" }` 를 포함하고 있는 `tslint.json` 파일을 추가해주시면 됩니다. 모든 새 패키지는 해당 파일을 가지고 있어야 합니다.
고쳐야 하지만 아직 고쳐지지 않은 린트(Lint) 결과가 있을 때에만 `tslint.json` 에서 린트 규칙(Lint rule)을 사용하지 않도록 설정할 수 있습니다. 예를 들어,
```js
{
"extends": "dtslint/dt.json",
"rules": {
// 이 패키지는 Function 형을 사용하고 있으며, 고치는 게 쉽지 않다.
"ban-types": false
}
}
```
(린트 규칙(Lint rule)이 절대로 적용되서는 안되는 경우에는, `// tslint:disable rule-name` 나 `//tslint:disable-next-line rule-name` 를 사용하는 것이 좋습니다. 후자가 더 나은 방식입니다.)
작성한 dts 파일을 타입스크립트 컴파일러로 돌려보기 위해 테스트 스크립트 내부적으로 [dtslint](https://github.com/Microsoft/dtslint)를 사용합니다.
#### \<my package>-tests.ts
@@ -304,11 +293,29 @@ f("one");
[dtslint](https://github.com/Microsoft/dtslint#write-tests) 저장소의 README 파일에서 더 자세한 내용을 확인하실 수 있습니다.
#### 검증하기
#### 린터
`npm test <package to test>` 명령을 통해 변경점을 테스트할 수 있습니다. 이 때, `<package to test>`은 테스트하고 싶은 패키지의 이름입니다.
자료형(Typing) 패키지를 린트(Lint)하려면, 패키지 디렉토리에 `{ "extends": "dtslint/dt.json" }` 를 포함하고 있는 `tslint.json` 파일을 추가해주시면 됩니다. 모든 새 패키지는 해당 파일을 가지고 있어야 합니다.
고쳐야 하지만 아직 고쳐지지 않은 린트(Lint) 결과가 있을 때에만 `tslint.json` 에서 린트 규칙(Lint rule)을 사용하지 않도록 설정할 수 있습니다. 예를 들어,
작성한 dts 파일을 타입스크립트 컴파일러로 돌려보기 위해 테스트 스크립트 내부적으로 [dtslint](https://github.com/Microsoft/dtslint)를 사용합니다.
```js
{
"extends": "dtslint/dt.json",
"rules": {
// 이 패키지는 Function 형을 사용하고 있으며, 고치는 게 쉽지 않다.
"ban-types": false
}
}
```
(린트 규칙(Lint rule)이 절대로 적용되서는 안되는 경우에는, `// tslint:disable rule-name` 나 `// tslint:disable-next-line rule-name` 를 사용하는 것이 좋습니다. 후자가 더 나은 방식입니다.)
#### package.json
일반적으로는 `package.json` 파일을 사용할 필요가 없습니다. 패키지가 퍼블리시(Publish)될 때 패키지를 위한 `package.json` 파일은 자동으로 생성됩니다.
가끔 보이는 `package.json` 파일은 의존하는 것들을 표시하기 위해 사용됩니다. [예시](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)를 한 번 보세요.
의존성을 제외한 다른 필드(Field)들, 그러니까 `"description"` 같은 것들은 사용해서는 안됩니다.
옛날 `@types` 패키지를 사용하고 싶으실 경우에도 `"dependencies": { "@types/foo": "x.y.z" }` 와 같은 내용을 `package.json` 파일에 넣으셔야 합니다.
### Definition Owners
@@ -350,13 +357,6 @@ NPM 의 패키지들은 수시간 안에 갱신될 겁니다. 만약 24 시간
외부 모듈(`export` 를 사용하는 모듈)을 사용할 경우, 임포트(import)를 사용해주세요.
환경과 관련된 모듈(ambient module)(`declare module` 를 쓰거나 전역 변수들을 선언한 모듈)을 사용할 경우, `<reference types="" />` 를 사용해주세요.
#### `package.json` 파일이 가끔 보이던데?
일반적으로는 `package.json` 파일을 사용할 필요가 없습니다. 패키지가 퍼블리시(Publish)될 때 패키지를 위한 `package.json` 파일은 자동으로 생성됩니다.
가끔 보이는 `package.json` 파일은 의존하는 것들을 표시하기 위해 사용됩니다. [예시](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)를 한 번 보세요.
의존성을 제외한 다른 필드(Field)들, 그러니까 `"description"` 같은 것들은 사용해서는 안됩니다.
옛날 `@types` 패키지를 사용하고 싶으실 경우에도 `"dependencies": { "@types/foo": "x.y.z" }` 와 같은 내용을 `package.json` 파일에 넣으셔야 합니다.
#### 어떤 패키지들에 `tslint.json` 이 없거나, `tsconfig.json` 에 `"noImplicitAny": true`, `"noImplicitThis": true`, 나 `"strictNullChecks": true` 가 없어요.
그럼 그 패키지들이 잘못된 겁니다. 고쳐서 풀 리퀘스트(Pull request)를 제출해주시면 고맙겠습니다.

81
README.md
View File

@@ -17,9 +17,10 @@
- [Create a new package](#create-a-new-package)
- [Common mistakes](#common-mistakes)
- [Removing a package](#removing-a-package)
- [Linter](#linter)
- [\<my package>-tests.ts](#my-package-teststs)
- [Running Tests](#running-tests)
- [\<my package>-tests.ts](#my-package-teststs)
- [Linter](#linter)
- [package.json](#packagejson)
</details>
- [Definition Owners](#definition-owners)
* [FAQ](#faq)
@@ -225,7 +226,7 @@ You can remove it by running `npm run not-needed -- typingsPackageName asOfVersi
Any other packages in Definitely Typed that referenced the deleted package should be updated to reference the bundled types.
You can get this list by looking at the errors from `npm run test-all`.
To fix the errors, add a `package.json` with `"dependencies": { "foo": "x.y.z" }`.
To fix the errors, [add a `package.json`](#packagejson) with `"dependencies": { "foo": "x.y.z" }`.
For example:
```json
@@ -241,29 +242,11 @@ When you add a `package.json` to dependents of `foo`, you will also need to open
If a package was never on Definitely Typed, it does not need to be added to `notNeededPackages.json`.
#### Linter
#### Running Tests
All new packages must be linted. To lint a package, add a `tslint.json` to that package containing
Test your changes by running `npm test <package to test>` where `<package to test>` is the name of your package.
```js
{
"extends": "dtslint/dt.json"
}
```
This should be the only content in a finished project's `tslint.json` file. If a `tslint.json` turns rules off, this is because that hasn't been fixed yet. For example:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(To indicate that a lint rule truly does not apply, use `// tslint:disable rule-name` or better, `//tslint:disable-next-line rule-name`.)
This script uses [dtslint](https://github.com/microsoft/dtslint) to run the TypeScript compiler against your dts files.
#### \<my package>-tests.ts
@@ -314,11 +297,42 @@ f("one");
For more details, see [dtslint](https://github.com/Microsoft/dtslint#write-tests) readme.
#### Running Tests
#### Linter
Test your changes by running `npm test <package to test>` where `<package to test>` is the name of your package.
All new packages must be linted. To lint a package, add a `tslint.json` to that package containing
This script uses [dtslint](https://github.com/microsoft/dtslint) to run the TypeScript compiler against your dts files.
```js
{
"extends": "dtslint/dt.json"
}
```
This should be the only content in a finished project's `tslint.json` file. If a `tslint.json` turns rules off, this is because that hasn't been fixed yet. For example:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(To indicate that a lint rule truly does not apply, use `// tslint:disable rule-name` or better, `// tslint:disable-next-line rule-name`.)
#### package.json
Usually you won't need this.
DefinitelyTyped'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/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.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.
### Definition Owners
@@ -366,19 +380,6 @@ NPM packages should update within a few minutes. If it's been more than an hour,
If the module you're referencing is an external module (uses `export`), use an import.
If the module you're referencing is an ambient module (uses `declare module`, or just declares globals), use `<reference types="" />`.
#### I notice some packages having a `package.json` here.
Usually you won't need this.
DefinitelyTyped'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/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.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`.
Then they are wrong, and we've not noticed yet. You can help by submitting a pull request to fix them.

80
README.pt.md
View File

@@ -18,9 +18,10 @@ Veja também o site [definitelytyped.org](http://definitelytyped.org), embora as
- [Crie um novo pacote](#crie-um-novo-pacote)
- [Erros comuns](#erros-comuns)
- [Removendo um pacote](#removendo-um-pacote)
- [Linter](#linter)
- [\<my package>-tests.ts](#my-package-teststs)
- [Verificando](#verificando)
- [\<my package>-tests.ts](#my-package-teststs)
- [Linter](#linter)
- [package.json](#package.json)
</details>
- [Donos de definição](#donos-de-definição)
* [FAQ](#faq)
@@ -227,7 +228,7 @@ Você pode removê-lo executando `npm run not-needed -- typingsPackageName asOfV
Quaisquer outros pacotes no Definitely Typed que referenciavam o pacote deletado devem ser atualizados para referenciar os tipos inclusos pelo pacote.
Você pode obter esta lista olhando os erros do `npm test`.
Para corrigir os erros, adicione o arquivo `package.json` com `"dependencies": { "foo": "x.y.z" }`.
Para corrigir os erros, [adicione o arquivo `package.json`](#packagejson) com `"dependencies": { "foo": "x.y.z" }`.
Por exemplo:
```json
@@ -243,28 +244,11 @@ Quando você adicionar um `package.json` aos dependentes de `foo`, você também
Se um pacote nunca esteve no Definitely Typed, ele não precisa ser adicionado ao `notNeededPackages.json`.
#### Linter
#### Verificando
Todos os novos pacotes devem passar pelo linter. Para habilitar o linter num pacote, adicione um `tslint.json` para aquele pacote, contendo:
```js
{
"extends": "dtslint/dt.json"
}
```
Teste suas mudanças executando o comando `npm test nome-do-pacote` onde `nome-do-pacote` é o nome do seu pacote.
Este deve ser o único conteúdo no arquivo `tslint.json` de um projeto finalizado. Se um `tslint.json` desabilitar certas regras, é porque elas ainda não foram corrigidas. Por exemplo:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// Este pacote usa o tipo Function, e vai dar trabalho para arrumar.
"ban-types": false
}
}
```
(Para indicar que uma regra de lint de fato não se aplica, use `// tslint:disable nome-da-regra` ou até mesmo, `//tslint:disable-next-line nome-da-regra`.)
Este script usa o [dtslint](https://github.com/Microsoft/dtslint) para executar o compilador de TypeScript em seus arquivos dts.
#### \<my package>-tests.ts
@@ -314,11 +298,42 @@ f("um");
Para mais detalhes, veja o arquivo readme do [dtslint](https://github.com/Microsoft/dtslint#write-tests).
#### Verificando
#### Linter
Teste suas mudanças executando o comando `npm test nome-do-pacote` onde `nome-do-pacote` é o nome do seu pacote.
Todos os novos pacotes devem passar pelo linter. Para habilitar o linter num pacote, adicione um `tslint.json` para aquele pacote, contendo:
```js
{
"extends": "dtslint/dt.json"
}
```
Este script usa o [dtslint](https://github.com/Microsoft/dtslint) para executar o compilador de TypeScript em seus arquivos dts.
Este deve ser o único conteúdo no arquivo `tslint.json` de um projeto finalizado. Se um `tslint.json` desabilitar certas regras, é porque elas ainda não foram corrigidas. Por exemplo:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// Este pacote usa o tipo Function, e vai dar trabalho para arrumar.
"ban-types": false
}
}
```
(Para indicar que uma regra de lint de fato não se aplica, use `// tslint:disable nome-da-regra` ou até mesmo, `// tslint:disable-next-line nome-da-regra`.)
#### package.json
Geralmente você não precisa disso.
O distribuidor de pacotes do Definitely Typed cria um `package.json` para pacotes sem dependências fora do Definitely Typed.
Um `package.json` pode ser incluído para especificar dependências que não são outros pacotes `@types`.
[Pikaday é um bom exemplo.](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)
Mesmo se você criar seu próprio `package.json`, você pode apenas especificar dependências; outros campos como `"description"` não são permetidos.
Você também precisa adicionar uma dependência à [lista de pacotes permitidos](https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.txt).
Essa lista é atualizada por um humano, o que nos dá a chance de nos certificar que os pacotes `@types` não dependem de pacotes maliciosos.
Nos caso raro que um pacote `@types` é deletado e removido em favor dos tipos enviados pelo pacote-fonte e você precise depender do pacote antigo `@types`, já removido, você pode adicionar a dependência no pacote `@types`.
Tenha certeza de explicar isso quando adicioná-lo à lista de pacotes permitidos, para que o mantenedor humano saiba o que está acontecendo.
### Donos de definição
@@ -366,19 +381,6 @@ Pacotes do NPM devem atualizar dentro de alguns minutos. Se já passou de uma ho
Se o módulo o qual você está referenciando é um módulo externo (usa `export`), use um import.
Se o módulo que você está referenciando é um módulo de ambiente (usa `declare module`, ou apenas declara globalmente), use `<reference types="" />`.
#### Eu percebi que alguns pacotes tem um `package.json` aqui.
Geralmente você não precisa disso.
O distribuidor de pacotes do Definitely Typed cria um `package.json` para pacotes sem dependências fora do Definitely Typed.
Um `package.json` pode ser incluído para especificar dependências que não são outros pacotes `@types`.
[Pikaday é um bom exemplo.](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)
Mesmo se você criar seu próprio `package.json`, você pode apenas especificar dependências; outros campos como `"description"` não são permetidos.
Você também precisa adicionar uma dependência à [lista de pacotes permitidos](https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.txt).
Essa lista é atualizada por um humano, o que nos dá a chance de nos certificar que os pacotes `@types` não dependem de pacotes maliciosos.
Nos caso raro que um pacote `@types` é deletado e removido em favor dos tipos enviados pelo pacote-fonte e você precise depender do pacote antigo `@types`, já removido, você pode adicionar a dependência no pacote `@types`.
Tenha certeza de explicar isso quando adicioná-lo à lista de pacotes permitidos, para que o mantenedor humano saiba o que está acontecendo.
#### Alguns pacotes não têm `tslint.json`, e alguns arquivos `tsconfig.json` não têm `"noImplicitAny": true`, `"noImplicitThis": true`, ou `"strictNullChecks": true`.
Então eles estão errados, e nós não notamos ainda. Você pode ajudar enviando uma pull request pra consertá-los.

69
README.ru.md
View File

@@ -18,9 +18,10 @@ _Вы также можете прочитать этот README на [англ
- [Создание нового пакета](#создание-нового-пакета)
- [Распространенные ошибки](#распространенные-ошибки)
- [Удаление пакета](#удаление-пакета)
- [Linter](#linter)
- [\<my package>-tests.ts](#my-package-teststs)
- [Проверка](#проверка)
- [\<my package>-tests.ts](#my-package-teststs)
- [Linter](#linter)
- [package.json](#packagejson)
</details>
- [Definition Owners](#definition-owners)
* [Часто задаваемые вопросы](#часто-задаваемые-вопросы)
@@ -227,33 +228,15 @@ Definitely Typed работает только благодаря вкладу
- `asOfVersion`: заглушка будет опубликована в `@types/foo` с этой версией. Должна быть выше, чем любая опубликованная на данный момент версия
- `libraryName`: описательное имя библиотеки, например, "Angular 2" вместо "angular2". (Если опущено, будет идентично "typingsPackageName".)
Любые другие пакеты в Definitely Typed которые ссылаются на удаленный пакет, должны быть обновлены для ссылки на связанные типы. Для этого добавьте в `package.json` ссыклу `"dependencies": { "foo": "x.y.z" }`.
Любые другие пакеты в Definitely Typed которые ссылаются на удаленный пакет, должны быть обновлены для ссылки на связанные типы. Для этого добавьте в [`package.json`](#packagejson) ссыклу `"dependencies": { "foo": "x.y.z" }`.
Если пакет никогда не был в Definitely Typed, его не нужно добавлять в `notNeededPackages.json`.
#### Linter
#### Проверка
Все новые пакеты должны быть проанализированы lint. Для этого добавьте `tslint.json` в этот пакет, содержащий
Протестируйте, запустив `npm test <package to test>` где `<package to test>` - это имя вашего пакета.
```js
{
"extends": "dtslint/dt.json"
}
```
Это должно быть единственным содержимым в файле `tslint.json` готового проекта. Если `tslint.json` отключает правила, это потому, что это еще не исправлено. Например:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(Чтобы указать, что правило lint действительно не применяется, используйте `// tslint:disable rule-name` или лучше, `//tslint:disable-next-line rule-name`.)
Этот скрипт использует [dtslint](https://github.com/Microsoft/dtslint) для запуска компилятора TypeScript на ваших dts файлах.
#### \<my package>-tests.ts
@@ -304,11 +287,36 @@ f('one');
Для получения дополнительной информации см. [dtslint](https://github.com/Microsoft/dtslint#write-tests) readme.
#### Проверка
#### Linter
Протестируйте, запустив `npm test <package to test>` где `<package to test>` - это имя вашего пакета.
Все новые пакеты должны быть проанализированы lint. Для этого добавьте `tslint.json` в этот пакет, содержащий
Этот скрипт использует [dtslint](https://github.com/Microsoft/dtslint) для запуска компилятора TypeScript на ваших dts файлах.
```js
{
"extends": "dtslint/dt.json"
}
```
Это должно быть единственным содержимым в файле `tslint.json` готового проекта. Если `tslint.json` отключает правила, это потому, что это еще не исправлено. Например:
```js
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
```
(Чтобы указать, что правило lint действительно не применяется, используйте `// tslint:disable rule-name` или лучше, `// tslint:disable-next-line rule-name`.)
#### package.json
Обычно вам это не нужно. При публикации пакета мы обычно автоматически создаем `package.json`.
`package.json` может быть включен для определения зависимостей. Вот [пример](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json).
Мы не разрешаем определять другие поля, такие как "description", вручную.
Кроме того, если вам нужно сослаться на более старую версию типизаций, вы должны сделать это, добавив в `package.json` строки `"dependencies": { "@types/foo": "x.y.z" }`.
### Definition Owners
@@ -350,13 +358,6 @@ Once a week the Definition Owners are synced to the file [.github/CODEOWNERS](ht
Если модуль, на который вы ссылаетесь, является внешним модулем (использует `export`), используйте import.
Если модуль, на который вы ссылаетесь, является окружающим модулем (использует `declare module`, или просто объявляет глобальные переменные), используйте `<reference types="" />`.
#### Я заметил, что у некоторых пакетов есть `package.json`.
Обычно вам это не нужно. При публикации пакета мы обычно автоматически создаем `package.json`.
`package.json` может быть включен для определения зависимостей. Вот [пример](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json).
Мы не разрешаем определять другие поля, такие как "description", вручную.
Кроме того, если вам нужно сослаться на более старую версию типизаций, вы должны сделать это, добавив в `package.json` строки `"dependencies": { "@types/foo": "x.y.z" }`.
#### В некоторых пакетах отсутствует `tslint.json`, а в некоторых `tsconfig.json` отсутствует `"noImplicitAny": true`, `"noImplicitThis": true`, или `"strictNullChecks": true`.
Тогда они не правы. Вы можете помочь, отправив PR, чтобы исправить их.