vhad/DefinitelyTyped
1
0
Fork 0
mirror of https://github.com/gosticks/DefinitelyTyped.git synced 2025-10-16 12:05:41 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Adds some admin docs (#41063)

Browse Source 
* Adds some admin docs

* Update admin manual

* Update docs/admin.md

Co-Authored-By: Nathan Shively-Sanders <293473+sandersn@users.noreply.github.com>

* More docs on admin

Co-authored-by: Nathan Shively-Sanders <293473+sandersn@users.noreply.github.com>
This commit is contained in:
Orta 2019-12-24 16:34:27 +00:00 committed by GitHub
parent a9bf23a732
commit 9f2b299e70
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 99 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@ -2,10 +2,10 @@
> The repository for *high quality* TypeScript type definitions.
Also see the [definitelytyped.org](http://definitelytyped.org) website, although information in this README is more up-to-date.
*You can also read this README in [Spanish](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.es.md), [Korean](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ko.md), [Russian](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ru.md), and [Chinese](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.cn.md)!*
*Link to [Admin manual](./docs/admin.md)*
## Table of Contents
* [Current status](#current-status)
@ -84,13 +84,12 @@ For example, if you run `npm dist-tags @types/react`, you'll see the following t
### Typescript 1.8 and earlier
* [Typings](https://github.com/typings/typings)
* Manually download from the `master` branch of this repository and place them in your project
* ~~[Typings](https://github.com/typings/typings)~~ (use preferred alternatives, typings is deprecated)
* ~~[NuGet](http://nuget.org/packages?q=DefinitelyTyped)~~ (use preferred alternatives, nuget DT type publishing has been turned off)
* Manually download from the `master` branch of this repository
You may need to add manual [references](http://www.typescriptlang.org/docs/handbook/triple-slash-directives.html).
## How can I contribute?
Definitely Typed only works because of contributions by users like you!
@ -183,7 +182,7 @@ For a good example package, see [base64-js](https://github.com/DefinitelyTyped/D
#### Common mistakes
* First, follow advice from the [handbook](http://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html).
* Formatting: Use 4 spaces. For new code, this is enforced by Prettier.
* Formatting: Use 4 spaces. Prettier is set up on this repo, so you can run `npm run prettier -- --write path/to/package`.
* `function sum(nums: number[]): number`: Use `ReadonlyArray` if a function does not write to its parameters.
* `interface Foo { new(): Foo; }`:
This defines a type of objects that are new-able. You probably want `declare class Foo { constructor(); }`.

94
docs/admin.md Normal file
View File

@ -0,0 +1,94 @@
## Admin Manual for Definitely Typed
Welcome! This is a resource for the person who is on call for DefinitelyTyped. The TypeScript team always has someone
assigned to DefinitelyTyped duty, where they do a week on-call. You can see the [schedule here](http://aka.ms/DTRotation).
When on-call, your goal is to try keep on top of the many open PRs for DefinitelyTyped; they are categorized into
different sections inside the [Projects board](https://github.com/DefinitelyTyped/DefinitelyTyped/projects/4) on this repo.
You should scan from left to right through the boards, and ideally try to start at the oldest PR in a section and work
your way through to the newest. There is a tool: [`focus-dt`](https://github.com/DefinitelyTyped/focus-dt) which can help with this.
Our goals are to provide a stable, high quality ecosystem of type definitions and that requires the compiler team
making sure that a PR does not break the ecosystem. This work isn't a code review in the usual sense, but an assessment
of how well the changes fit the rest of the type definitions and if it could break builds for our users or our systems.
With the impact understood, your job is to delegate to the people who actually know how to review the code: users
of the library who have agreed to look after the types.
### Looking at a PR
For a [quick TLDR overview, you can read these slides](https://docs.google.com/presentation/d/1Q4xfZSY7d9yHhtxSyb-DE85fTXB38RyF3nnyVyvenwc/edit#slide=id.p).
Some key concepts:
- Popular packages can break more installs, and will need more time and focus
- There are a handful of authors who have shipped a lot of high quality contributions who you can happily delegate to
##### Amending an existing DefinitelyTyped Package
An ideal PR to a DT package looks like:
- A link in the PR description to the API being added
- Only additions to the existing types
- Test code which covers the existing use case
Most of the PRs are like this, in which case then a review for that PR should be pretty quick. Look through the code
changes, then see if there are comments asking for the merge to be delayed. If not, then you're good to merge. You
can then leave a thanks comment and hit the merge button.
Constraints which you should consider:
- Will the PR break existing code?
- This can sometimes be hard to decipher from the diff, e.g. an additional only PR may break superclasses of a class
- We try to make sure that types are a semver match on `major.min` for the library they represent
- A build breaking change therefore can be a trade-off where you have to talk with the library maintainer, and get their sign-offs that it is worth it
- Is it popular? (e.g. do you recognise it) if so, it should probably have two sign-offs
- The PR has merge conflicts, you can try edit the PR using the GitHub UI if it's a trivial change, then come back tomorrow
- The PR has no tests, possibly the package on DT hasn't got tests set up. You can decide if that's a blocker or not depending on how likely the code is going to break existing code
- The `tslint.json` does not have exceptions to the rules in it
- Strict mode is `strict: true` or equivalent four (five?) settings in tsconfig.json
- Make sure export default is actually default in the source.
```ts
// Cannot have `export default` in the dts
modele.exports = {
thing: () => "hello world"
}
```
vs
```ts
// Can import via `export default`
modele.exports.default = {
thing: () => "hello world"
}
```
`react-*` packages get a pass on this.
- Their `tsconfig.json` should never have `esModuleInterop: true`, which would hide the above issue.
##### New DefinitelyTyped Package
- Is the author also a maintainer of the library? If so, they could use [`--declaration` and `--allowJs`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#--declaration-and---allowjs) in TypeScript to generate their types.
### Useful Repos and Links
The process of handling PRs:
- [DT projects](https://github.com/DefinitelyTyped/DefinitelyTyped/projects/4) - an automated board saying where open PRs live
- [dt-merge-bot](https://github.com/RyanCavanaugh/dt-mergebot/) - the bot which sets the labels on PRs, and update's project status
- [dt-merge-bot graphql](https://github.com/RyanCavanaugh/dt-mergebot/tree/use-graphql) - the WIP v2 of the bot to automate the labels/projects
- [focus-dt](https://github.com/DefinitelyTyped/focus-dt) - a tool which controls chrome to load up the next PR to review, so you can focus
- [dtslint](https://github.com/microsoft/dtslint) - the CLI tool used to validate PRs on DefinitelyTyped
The process of deploying changes:
- [types-publisher](https://github.com/microsoft/types-publisher) - when a PR is merged, types-publisher moves the contents to NPM/GitHub Package Repository
- [CI](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build) - the build pipelines on Azure which does most of the work
Recommendations we make:
- [dts-gen](https://github.com/Microsoft/dts-gen) - a tool for creating a DT folder automatically