khaledelansari/guidelines

Guidelines for @types contributors

Guidelines

Simple documentation for @types contributors.

Repository

If you're creating a repository under @types, make sure to follow the existing naming guidelines. That is, <source>-<lib name>. The list of sources can be viewed in the registry.

Structure

Using npm-quickly-copy-file as an example, make sure you have the following set up to ease contributing.

1. Make sure you have a descriptive README with, at least, a link to the source repository (README.md)
2. Set up tsconfig.json using the minimum required settings (see tsconfig.json settings) (tsconfig.json)
3. The work should be licensed under MIT, or similar, to enable redistribution (LICENSE)
4. Create a package.json with the @types/<pkg> name, testing scripts (using tsc and ts-node), typings field and development dependencies - there should be no implicit dependencies (package.json)
5. Create the typings.json version with original package name (typings.json)
6. I recommend checking in an .editorconfig file for people to follow (.editorconfig)
7. Make sure all generated assets are .gitignore'd (.gitignore)
8. Add the tslint.json configuration extending tslint-config-standard (tslint.json)
9. Write the definition, mirroring the original JavaScript source code with types (index.d.ts)
10. Make sure you include some tests for future contributors (test.ts)
11. Set up .travis.yml for CI (.travis.yml)
12. Enable Greenkeeper and Travis CI

Quickly Enable Travis CI and Greenkeeper

gem install travis
npm install -g greenkeeper

travis enable
greenkeeper enable

P.S. You should have the JavaScript source of the typings as a devDependency, using the ~ or 1.0.x version ranges. If Greenkeeper detects a new version, you'll have a chance to review the changes in a Pull Request.

.travis.yml

sudo: false
language: node_js

notifications:
  email:
    on_success: never
    on_failure: change

script:
  - npm run lint
  - npm run bundle
  - npm rm tslint
  - npm install $TYPESCRIPT --force
  - npm run exec

env:
  - [email protected]
  - TYPESCRIPT=typescript@latest
  - TYPESCRIPT=typescript@next

node_js:
  - "stable"

Branching Vs Folder Versions

The current practice for typing multiple versions in folders vs branches is undecided. The most obvious reason to target multiple branches over folders is supporting npm natively. NPM can not install using folders.

tsconfig.json

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es2015"],
    "module": "commonjs",
    "noEmit": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

For node typings, it also makes sense to use lib.core.d.ts only. This enables people to disable browser typings without any issue.