1 # Instructions for Logging Issues 2 3 ## 1. Read the FAQ 4 5 Please [read the FAQ](https://github.com/Microsoft/TypeScript/wiki/FAQ) before logging new issues, even if you think you have found a bug. 6 7 Issues that ask questions answered in the FAQ will be closed without elaboration. 8 9 ## 2. Search for Duplicates 10 11 [Search the existing issues](https://github.com/Microsoft/TypeScript/search?type=Issues) before logging a new one. 12 13 Some search tips: 14 * *Don't* restrict your search to only open issues. An issue with a title similar to yours may have been closed as a duplicate of one with a less-findable title. 15 * Check for synonyms. For example, if your bug involves an interface, it likely also occurs with type aliases or classes. 16 * Search for the title of the issue you're about to log. This sounds obvious but 80% of the time this is sufficient to find a duplicate when one exists. 17 * Read more than the first page of results. Many bugs here use the same words so relevancy sorting is not particularly strong. 18 * If you have a crash, search for the first few topmost function names shown in the call stack. 19 20 ## 3. Do you have a question? 21 22 The issue tracker is for **issues**, in other words, bugs and suggestions. 23 If you have a *question*, please use [Stack Overflow](http://stackoverflow.com/questions/tagged/typescript), [Gitter](https://gitter.im/Microsoft/TypeScript), your favorite search engine, or other resources. 24 Due to increased traffic, we can no longer answer questions in the issue tracker. 25 26 ## 4. Did you find a bug? 27 28 When logging a bug, please be sure to include the following: 29 * What version of TypeScript you're using (run `tsc --v`) 30 * If at all possible, an *isolated* way to reproduce the behavior 31 * The behavior you expect to see, and the actual behavior 32 33 You can try out the nightly build of TypeScript (`npm install typescript@next`) to see if the bug has already been fixed. 34 35 ## 5. Do you have a suggestion? 36 37 We also accept suggestions in the issue tracker. 38 Be sure to [check the FAQ](https://github.com/Microsoft/TypeScript/wiki/FAQ) and [search](https://github.com/Microsoft/TypeScript/issues?utf8=%E2%9C%93&q=is%3Aissue) first. 39 40 In general, things we find useful when reviewing suggestions are: 41 * A description of the problem you're trying to solve 42 * An overview of the suggested solution 43 * Examples of how the suggestion would work in various places 44 * Code examples showing e.g. "this would be an error, this wouldn't" 45 * Code examples showing the generated JavaScript (if applicable) 46 * If relevant, precedent in other languages can be useful for establishing context and expected behavior 47 48 # Instructions for Contributing Code 49 50 ## What You'll Need 51 52 0. [A bug or feature you want to work on](https://github.com/microsoft/TypeScript/labels/help%20wanted)! 53 1. [A GitHub account](https://github.com/join). 54 2. A copy of the TypeScript code. See the next steps for instructions. 55 3. [Node](https://nodejs.org), which runs JavaScript locally. Current or LTS will both work. 56 4. An editor. [VS Code](https://code.visualstudio.com) is the best place to start for TypeScript. 57 5. The gulp command line tool, for building and testing changes. See the next steps for how to install it. 58 59 ## Get Started 60 61 1. Install node using the version you downloaded from [nodejs.org](https://nodejs.org). 62 2. Open a terminal. 63 3. Make a fork—your own copy—of TypeScript on your GitHub account, then make a clone—a local copy—on your computer. ([Here are some step-by-step instructions](https://github.com/anitab-org/mentorship-android/wiki/Fork%2C-Clone-%26-Remote)). Add `--depth=1` to the end of the `git clone` command to save time. 64 4. Install the gulp command line tool: `npm install -g gulp-cli` 65 5. Change to the TypeScript folder you made: `cd TypeScript` 66 6. Install dependencies: `npm ci` 67 7. Make sure everything builds and tests pass: `gulp runtests-parallel` 68 8. Open the Typescript folder in your editor. 69 9. Follow the directions below to add and debug a test. 70 71 ## Tips 72 73 ### Faster clones 74 75 The TypeScript repository is relatively large. To save some time, you might want to clone it without the repo's full history using `git clone --depth=1`. 76 77 ### Using local builds 78 79 Run `gulp` to build a version of the compiler/language service that reflects changes you've made. You can then run `node <repo-root>/built/local/tsc.js` in place of `tsc` in your project. For example, to run `tsc --watch` from within the root of the repository on a file called `test.ts`, you can run `node ./built/local/tsc.js --watch test.ts`. 80 81 ## Contributing bug fixes 82 83 TypeScript is currently accepting contributions in the form of bug fixes. A bug must have an issue tracking it in the issue tracker that has been approved (labelled ["help wanted"](https://github.com/Microsoft/TypeScript/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or in the "Backlog milestone") by the TypeScript team. Your pull request should include a link to the bug that you are fixing. If you've submitted a PR for a bug, please post a comment in the bug to avoid duplication of effort. 84 85 ## Contributing features 86 87 Features (things that add new or improved functionality to TypeScript) may be accepted, but will need to first be approved (labelled ["help wanted"](https://github.com/Microsoft/TypeScript/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or in the "Backlog" milestone) by a TypeScript project maintainer in the suggestion issue. Features with language design impact, or that are adequately satisfied with external tools, will not be accepted. 88 89 ## Legal 90 91 You will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright. Upon submitting a pull request, you will automatically be given instructions on how to sign the CLA. 92 93 ## Housekeeping 94 95 Your pull request should: 96 97 * Include a description of what your change intends to do 98 * Be based on reasonably recent commit in the **master** branch 99 * Include adequate tests 100 * At least one test should fail in the absence of your non-test code changes. If your PR does not match this criteria, please specify why 101 * Tests should include reasonable permutations of the target fix/change 102 * Include baseline changes with your change 103 * Follow the code conventions described in [Coding guidelines](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines) 104 * To avoid line ending issues, set `autocrlf = input` and `whitespace = cr-at-eol` in your git configuration 105 106 ## Contributing `lib.d.ts` fixes 107 108 There are three relevant locations to be aware of when it comes to TypeScript's library declaration files: 109 110 * `src/lib`: the location of the sources themselves. 111 * `lib`: the location of the last-known-good (LKG) versions of the files which are updated periodically. 112 * `built/local`: the build output location, including where `src/lib` files will be copied to. 113 114 Any changes should be made to [src/lib](https://github.com/Microsoft/TypeScript/tree/master/src/lib). **Most** of these files can be updated by hand, with the exception of any generated files (see below). 115 116 Library files in `built/local/` are updated automatically by running the standard build task: 117 118 ```sh 119 gulp 120 ``` 121 122 The files in `lib/` are used to bootstrap compilation and usually **should not** be updated unless publishing a new version or updating the LKG. 123 124 ### Modifying generated library files 125 126 The files `src/lib/dom.generated.d.ts` and `src/lib/webworker.generated.d.ts` both represent type declarations for the DOM and are auto-generated. To make any modifications to them, you will have to direct changes to https://github.com/Microsoft/TSJS-lib-generator 127 128 ## Running the Tests 129 130 To run all tests, invoke the `runtests-parallel` target using gulp: 131 132 ```Shell 133 gulp runtests-parallel 134 ``` 135 136 This will run all tests; to run only a specific subset of tests, use: 137 138 ```Shell 139 gulp runtests --tests=<regex> 140 ``` 141 142 e.g. to run all compiler baseline tests: 143 144 ```Shell 145 gulp runtests --tests=compiler 146 ``` 147 148 or to run a specific test: `tests\cases\compiler\2dArrays.ts` 149 150 ```Shell 151 gulp runtests --tests=2dArrays 152 ``` 153 154 ## Debugging the tests 155 156 You can debug with VS Code or Node instead with `gulp runtests --inspect`: 157 158 ```Shell 159 gulp runtests --tests=2dArrays --inspect 160 ``` 161 162 You can also use the [provided VS Code launch configuration](./.vscode/launch.template.json) to launch a debug session for an open test file. Rename the file 'launch.json', open the test file of interest, and launch the debugger from the debug panel (or press F5). 163 164 ## Adding a Test 165 166 To add a new test case, add a `.ts` file in `tests\cases\compiler` with code that shows the your bug is now fixed, or your new feature now works. 167 168 These files support metadata tags in the format `// @metaDataName: value`. 169 The supported names and values are the same as those supported in the compiler itself, with the addition of the `fileName` flag. 170 `fileName` tags delimit sections of a file to be used as separate compilation units. 171 They are useful for testing modules. 172 See below for examples. 173 174 **Note** that if you have a test corresponding to a specific area of spec compliance, you can put it in the appropriate subfolder of `tests\cases\conformance`. 175 **Note** that test filenames must be distinct from all other test names, so you may have to work a bit to find a unique name if it's something common. 176 177 ### Tests for multiple files 178 179 When you need to mimic having multiple files in a single test to test features such as "import", use the `filename` tag: 180 181 ```ts 182 // @filename: file1.ts 183 export function f() { 184 } 185 186 // @filename: file2.ts 187 import { f as g } from "file1"; 188 189 var x = g(); 190 ``` 191 192 ## Managing the baselines 193 194 Most tests generate "baselines" to find differences in output. 195 As an example, compiler tests usually emit one file each for 196 197 - the `.js` and `.d.ts` output (all in the same `.js` output file), 198 - the errors produced by the compiler (in an `.errors.txt` file), 199 - the types of each expression (in a `.types` file), 200 - the symbols for each identifier (in a `.symbols` file), and 201 - the source map outputs for files if a test opts into them (in a `.js.map` file). 202 203 When a change in the baselines is detected, the test will fail. To inspect changes vs the expected baselines, use 204 205 ```Shell 206 git diff --diff-filter=AM --no-index ./tests/baselines/reference ./tests/baselines/local 207 ``` 208 209 Alternatively, you can set the `DIFF` environment variable and run `gulp diff`, or manually run your favorite folder diffing tool between `tests/baselines/reference` and `tests/baselines/local`. Our team largely uses Beyond Compare and WinMerge. 210 211 After verifying that the changes in the baselines are correct, run 212 213 ```Shell 214 gulp baseline-accept 215 ``` 216 217 This will change the files in `tests\baselines\reference`, which should be included as part of your commit. 218 Be sure to validate the changes carefully -- apparently unrelated changes to baselines can be clues about something you didn't think of. 219 220 ## Localization 221 222 All strings the user may see are stored in [`diagnosticMessages.json`](./src/compiler/diagnosticMessages.json). 223 If you make changes to it, run `gulp generate-diagnostics` to push them to the `Diagnostic` interface in `diagnosticInformationMap.generated.ts`. 224 225 See [coding guidelines on diagnostic messages](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines#diagnostic-messages). 226