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.

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. There are a few way to do this:
  1. Simply compile the test file:
     • tsc --noImplicitAny your/code.tests.ts.
  2. Run npm test before sending your pull request.
     • If you created new files add them to git so the tester picks them as changes.
     • 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.
  3. Enable Travis on your DT fork and test online.
     • See note below on how to enable this.
     • This takes a few steps to do but is faster for big cascading changes (like changing JQuery)
  4. Depend on the automated test on Travis that runs after you send a PR.
     • If you need many attempts to fix errors then please flatten the history and clean the commit message.

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. See the TypeScript wiki for some tips.

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

Example:

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

Whitespaces

To be consistent across all .ts files, please use Spaces (not Tabs) with indent size of 4 which are the default settings in Visual Studio for TypeScript projects.

See: Visual Studio Tools menu > Options > Text Editor > TypeScript > Tabs

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 and push it to your DT fork. If the Pull Request uses the same branch it will be update automatically and the tests will run again.

If you need multiple tries to make it work then please flatten your commits so the history is moderately clean (please also minimise 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 enable Travis for your own DT fork if you like: go to Travis and sign-up for free if you haven't yet. Then go to your account and enable your DT fork. This will run Travis same as on DT and allows you to experiment freely. You can review your fork's build status via the menu on the left side of the Travis homepage after you enabled the hook AND pushed some code to the repo.

Large contributions and changes

If you plan to start a new definition make sure to check the issues first and/or leave a message that you are working on it so you're not do duplicating work. 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 again.

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 up to a week before someone has the focus+time to look at a PR and merge it. If your contributions stays pending and get buried then feel free to politely ping/bump.

Thanks for contributing!