You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+95-13Lines changed: 95 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,63 @@
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/issues?utf8=%E2%9C%93&q=is%3Aissue) before logging a new one.
12
+
13
+
## 3. Do you have a question?
14
+
15
+
The issue tracker is for **issues**, in other words, bugs and suggestions.
16
+
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.
17
+
Due to increased traffic, we can no longer answer questions in the issue tracker.
18
+
19
+
## 4. Did you find a bug?
20
+
21
+
When logging a bug, please be sure to include the following:
22
+
* What version of TypeScript you're using (run `tsc --v`)
23
+
* If at all possible, an *isolated* way to reproduce the behavior
24
+
* The behavior you expect to see, and the actual behavior
25
+
26
+
You can try out the nightly build of TypeScript (`npm install typescript@next`) to see if the bug has already been fixed.
27
+
28
+
## 5. Do you have a suggestion?
29
+
30
+
We also accept suggestions in the issue tracker.
31
+
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.
32
+
33
+
In general, things we find useful when reviewing suggestions are:
34
+
* A description of the problem you're trying to solve
35
+
* An overview of the suggested solution
36
+
* Examples of how the suggestion would work in various places
37
+
* Code examples showing e.g. "this would be an error, this wouldn't"
38
+
* Code examples showing the generated JavaScript (if applicable)
39
+
* If relevant, precedent in other languages can be useful for establishing context and expected behavior
40
+
41
+
# Instructions for Contributing Code
42
+
1
43
## Contributing bug fixes
44
+
2
45
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 ("Milestone == Community") 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.
3
46
4
47
## Contributing features
48
+
5
49
Features (things that add new or improved functionality to TypeScript) may be accepted, but will need to first be approved (marked as "Milestone == Community" by a TypeScript coordinator with the message "Approved") in the suggestion issue. Features with language design impact, or that are adequately satisfied with external tools, will not be accepted.
6
50
7
51
Design changes will not be accepted at this time. If you have a design change proposal, please log a suggestion issue.
8
52
9
53
## Legal
54
+
10
55
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.
11
56
12
-
Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.microsoft.com to sign digitally. Alternatively, download the agreement ([Microsoft Contribution License Agreement.docx](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=822190) or [Microsoft Contribution License Agreement.pdf](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=921298)), sign, scan, and email it back to <cla@microsoft.com>. Be sure to include your github user name along with the agreement. Once we have received the signed CLA, we'll review the request. Please note that we're currently only accepting pull requests of bug fixes rather than new features.
57
+
Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.microsoft.com to sign digitally. Alternatively, download the agreement ([Microsoft Contribution License Agreement.docx](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=822190) or [Microsoft Contribution License Agreement.pdf](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=921298)), sign, scan, and email it back to <cla@microsoft.com>. Be sure to include your github user name along with the agreement. Once we have received the signed CLA, we'll review the request.
13
58
14
59
## Housekeeping
60
+
15
61
Your pull request should:
16
62
17
63
* Include a description of what your change intends to do
@@ -25,11 +71,27 @@ Your pull request should:
25
71
* Tests should include reasonable permutations of the target fix/change
26
72
* Include baseline changes with your change
27
73
* All changed code must have 100% code coverage
28
-
* Follow the code conventions descriped in [Coding guidelines](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines)
74
+
* Follow the code conventions described in [Coding guidelines](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines)
29
75
* To avoid line ending issues, set `autocrlf = input` and `whitespace = cr-at-eol` in your git configuration
30
76
77
+
## Contributing `lib.d.ts` fixes
78
+
79
+
The library sources are in: [src/lib](https://github.com/Microsoft/TypeScript/tree/master/src/lib)
80
+
81
+
Library files in `built/local/` are updated by running
82
+
```Shell
83
+
jake
84
+
```
85
+
86
+
The files in `lib/` are used to bootstrap compilation and usually do not need to be updated.
87
+
88
+
#### `src/lib/dom.generated.d.ts` and `src/lib/webworker.generated.d.ts`
89
+
90
+
These two files represent the DOM typings and are auto-generated. To make any modifications to them, please submit a PR to https://github.com/Microsoft/TSJS-lib-generator
91
+
31
92
## Running the Tests
32
-
To run all tests, invoke the runtests target using jake:
93
+
94
+
To run all tests, invoke the `runtests` target using jake:
33
95
34
96
```Shell
35
97
jake runtests
@@ -47,23 +109,42 @@ e.g. to run all compiler baseline tests:
47
109
jake runtests tests=compiler
48
110
```
49
111
50
-
or to run specifc test: `tests\cases\compiler\2dArrays.ts`
112
+
or to run a specific test: `tests\cases\compiler\2dArrays.ts`
51
113
52
114
```Shell
53
115
jake runtests tests=2dArrays
54
116
```
55
117
118
+
## Debugging the tests
119
+
120
+
To debug the tests, invoke the `runtests-browser` task from jake.
121
+
You will probably only want to debug one test at a time:
122
+
123
+
```Shell
124
+
jake runtests-browser tests=2dArrays
125
+
```
126
+
127
+
You can specify which browser to use for debugging. Currently Chrome and IE are supported:
You can debug with VS Code or Node instead with `jake runtests debug=true`:
134
+
135
+
```Shell
136
+
jake runtests tests=2dArrays debug=true
137
+
```
138
+
56
139
## Adding a Test
57
-
To add a new testcase, simply place a `.ts` file in `tests\cases\compiler` containing code that exemplifies the bugfix or change you are making.
58
140
59
-
These files support metadata tags in the format `// @metaDataName: value`. The supported names and values are:
141
+
To add a new test case, simply place a `.ts` file in `tests\cases\compiler` containing code that exemplifies the bugfix or change you are making.
60
142
61
-
*`comments`, `sourcemap`, `noimplicitany`, `declaration`: true or false (corresponds to the compiler command-line options of the same name)
62
-
*`target`: ES3 or ES5 (same as compiler)
63
-
*`out`, outDir: path (same as compiler)
64
-
*`module`: local, commonjs, or amd (local corresponds to not passing any compiler --module flag)
65
-
*`fileName`: path
66
-
* These tags delimit sections of a file to be used as separate compilation units. They are useful for tests relating to modules. See below for examples.
143
+
These files support metadata tags in the format `// @metaDataName: value`.
144
+
The supported names and values are the same as those supported in the compiler itself, with the addition of the `fileName` flag.
145
+
`fileName` tags delimit sections of a file to be used as separate compilation units.
146
+
They are useful for tests relating to modules.
147
+
See below for examples.
67
148
68
149
**Note** that if you have a test corresponding to a specific spec compliance item, you can place it in `tests\cases\conformance` in an appropriately-named subfolder.
69
150
**Note** that filenames here must be distinct from all other compiler testcase names, so you may have to work a bit to find a unique name if it's something common.
@@ -86,6 +167,7 @@ var x = g();
86
167
One can also write a project test, but it is slightly more involved.
87
168
88
169
## Managing the Baselines
170
+
89
171
Compiler testcases generate baselines that track the emitted `.js`, the errors produced by the compiler, and the type of each expression in the file. Additionally, some testcases opt in to baselining the source map output.
90
172
91
173
When a change in the baselines is detected, the test will fail. To inspect changes vs the expected baselines, use
@@ -102,4 +184,4 @@ jake baseline-accept
102
184
103
185
to establish the new baselines as the desired behavior. This will change the files in `tests\baselines\reference`, which should be included as part of your commit. It's important to carefully validate changes in the baselines.
104
186
105
-
**Note** that baseline-accept should only be run after a full test run! Accepting baselines after running a subset of tests will delete baseline files for the tests that didn't run.
187
+
**Note** that `baseline-accept` should only be run after a full test run! Accepting baselines after running a subset of tests will delete baseline files for the tests that didn't run.
0 commit comments