From 85bfc993ac2ca07779f4c8e8cea892ce64fc30d9 Mon Sep 17 00:00:00 2001 From: Orta Therox Date: Mon, 16 Dec 2019 11:58:43 +0000 Subject: [PATCH] Adds some admin docs --- README.md | 11 +++++----- docs/admin.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 6 deletions(-) create mode 100644 docs/admin.md diff --git a/README.md b/README.md index c523ceda58..ff6e1492ed 100644 --- a/README.md +++ b/README.md @@ -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(); }`. diff --git a/docs/admin.md b/docs/admin.md new file mode 100644 index 0000000000..f21af60d95 --- /dev/null +++ b/docs/admin.md @@ -0,0 +1,59 @@ +## 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 latest PR 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. + +### Looking at a PR + +Some useful heuristics for looking at a PR: + +##### 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. + + +##### 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 on merging: + +- Will the PR break existing code? If so, check that there's a semver bump +- 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 + + +### 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