How to contribute

Creating a definition file:

The official TypeScript wiki on codeplex.com has a great article on how to write a good type declaration file. It is recommended you read this as it covers some important choices and considerations.

Quality Criteria

To ensure the quality of DefinitelyTyped repository, the typings must meet the following criteria:

Version

• Definition files should be called library.d.ts. In case there are multiple versions supported, the latest one will be without a version number in the file name. Older versions will be in the form of library-1.0.d.ts.

Header

• The typing must have a header with the following format:

// Type definitions for [LIBRARY NAME]
// Project: [LIBRARY URL]
// Definitions by: [AUTHOR NAME] <[AUTHOR URL]>
// Definitions: https://github.com/borisyankov/DefinitelyTyped

Example:

// Type definitions for Backbone 0.9.10
// Project: http://backbonejs.org/
// Definitions by: Boris Yankov <https://github.com/borisyankov/>
// Definitions: https://github.com/borisyankov/DefinitelyTyped	

Location

• The typing must be placed in a folder. The folder name must be similar to library name.

Example: qunit.d.ts in in a folder named qunit

Documentation

• Take advantage of TypeScript JSDoc support.

Tests

• The typing must have tests. These tests must be in a files called library-tests.ts. They are not runnable, in the TDD way. They contain code that should compile with no errors, usually taken from the documentation samples of the library.

Example: backbone.d.ts has a test file named backbone-tests.ts Here you can see a real test file.

• Check your code. Run npm test before sending your pull request.
  • Tests must be run from the DefinitelyTyped project's root directory.
  • You'll need to run npm update once to download the packages required by the test suite.
  • If test fail try recompiling your code using tsc --noImplicitAny your/code.d.ts to show where the typings leak any. Fix your code or add your/code.d.ts.tscparams.

If you need to use tscparams note that the contents of tscparams should be quoted. i.e. "" e.g. https://github.com/borisyankov/DefinitelyTyped/blob/master/ace/all-tests.ts.tscparams

Namespacing

• Be careful to use a module to avoid conflicts to your internal interfaces and the interfaces from another typings.

The jQuery.bbq typing has the interfaces in a module named JQueryBbq

Example:

    module JQueryBbq {
        interface JQuery {
            //...
        }
        //...
    }
    interface JQueryStatic {
        bbq: JQueryBbq.JQuery;
        //...
    }

Readme

• Update the README file to put a reference to your definition with the following style:

* [LIBRARY NAME WITH LINK] (by [AUTHOR NAME WITH LINK])

Example:

• Ace Cloud9 Editor (by Diullei Gomes)

Pull Requests FAQ

This is general guidance to answer common questions.

Getting latest upstream changes

You don't need to do this unless we request you to do so.

Initially make sure you have DT added as an upstream remote in your fork. Do this by :

git remote add upstream https://github.com/borisyankov/DefinitelyTyped.git

Now whenever you want the latest changes from DT added to your local branch just run these two commands :

git fetch upstream
# Fetches any new changes from DefinitelyTyped
git merge upstream/master
# Merges any changes fetched into your working files

Broken Build

If tests fail and you know how to fix them, just add a commit to fix that error in your local branch. The Pull Request will update automatically and tests will run again.

If you need many tries to make it work then please flatten your commits so the history is moderately clean (please cleanup the commit message). You could git push --force (careful!) the flat commit over your earlier commits in the same branch and the PR will be automatically updated.

Multiple contributions

It is recommended to split your contributions for different JS packages into their own git branches so you can have multiple pending PR's.

Travis CI for your DT fork

You can now also enable Travis for your DT fork. Go to the Travis CI website and sing-up for free if you haven't yet. Then go to your account and enable your fork. This will run Travis-CI same as on DT and allows you to experiment freely.

Large contributions and big changes

If you plan to start a new definition it could be wise to check the issues and/or leave a message that mentions your are working on something so you're not duplicating work with someone else. Coordination with fellow users is always recommended.

If you think you need to make big changes to a existing definition it could be handy to review the git history and create a new Issue where you @mention previous authors and see if they agree and/or want to get involved.

Merging

DefinitelyTyped is managed by a group of enthusiasts who volunteer their free time to review and merge the contributions. This means it can potentially take a few days or even a week before someone has the focus+time to look at your PR and merge it. If your contributions stays pending too long or gets buried then feel free to politely ping/bump.

Thanks for contributing!