DefinitelyTyped/definitelytyped.github.io

Best Practices Guide and Enhancement Guide

Closed this issue · 5 comments

psnider commented

I sometimes find it difficult to work with definition files, as they are structured all sorts of different ways, and often contain errors, including structural errors that make it difficult to use definitions in node.js.

I would like a Best Practices Guide, which outlines how definition files should be structured, documented, and managed. In particular, I would like clear guidance for supporting internal and external modules.

I would also like an Enhancement Guide for how to improve any definition files that don't meet best practices. This would probably require a versioning scheme so people using an older definition file can continue to use theirs, without a newer one breaking their code.

A few of the problems that I encounter frequently are:

  • definitions written only for internal modules
  • type names and module names that don't match the npm documentation
  • types exposed globally, instead of being wrapped in a module.
  • incorrect or loose overloads
  • missing types

I realize that definition files often start out sparse and get filled out as people find need.
But I'm unsure how to proceed when I find an error in an existing file, or that the existing file is out of date with respect to newer versions.

I would appreciate any references or guidance you can offer me.

johnnyreilly commented

Try this? Not perfect but a start...

psnider commented

I've read all of the pages I can find http://definitelytyped.org, but these pages don't seem to address the issues I raised.

What should I do when I find an error?
For example, I just added the example code from https://www.npmjs.com/package/nodemailer to ./nodemailer/nodemailer-tests.ts, and it won't compile. As I start to investigate, it seems that there are other things wrong with this definition file, and it may be too much for me to repair.

What is the procedure for correcting these types of problems?
Is there a way for me to register interest in helping, or in getting support from the community?
Or should I just raise issues here?

johnnyreilly commented

It's probably slightly confusing as we're not organised as you might expect. We're not really at https://github.com/DefinitelyTyped/DefinitelyTyped/ but are actually at https://github.com/borisyankov/DefinitelyTyped/. (We're supposed to be moving at some point but haven't got round to it for reasons that I forget.)

The best thing to do is to log issues against the borisyankov DefinitelyTyped repo (if issues haven't been already logged). I'm guessing there may be something wrong with your environment if you can't compile. We ensure tests pass before we merge. Perhaps you've got an out of date copy of TypeScript installed?

psnider commented

Thanks, I'll start logging issues at borisyankov/DefinitelyTyped.

My results are consistent with yours.
The errors with nodemailer appeared after I added some example code from the nodemailer npm page.

BTW, I'm using TS 1.3, And I am working off of borisyankov/DefinitelyTyped.

psnider commented

Also, I recently wrote a definition file for the imap module on npm: https://www.npmjs.com/package/imap

My pull request is: DefinitelyTyped/DefinitelyTyped#3324

It took me nearly two months (of spare time) to get this thing working, and structured how I like.
I'm sure that there are still problems with it, but I believe I've met the existing guidelines.