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
about: Instructions for Copilot to port a PR from microsoft/TypeScript
4
+
title: 'Port TypeScript PR #[NNNNN]'
5
+
labels: Porting PR
6
+
assignees: ''
7
+
8
+
---
9
+
10
+
This repository is a port of microsoft/TypeScript from TypeScript to Go. Since the port began, the following pull request was applied to microsoft/TypeScript. An equivalent change now needs to be applied here.
- Squash commit diff: <!-- Copy the squash commit link and append ".patch", e.g. https://github.com/microsoft/TypeScript/commit/a271797c1a95494e5f7aa8075c01941ad25cad08.patch -->
16
+
17
+
## Instructions
18
+
19
+
1. Use `playwright` to view the PR listed above
20
+
2. Apply the edits made in that PR to this codebase, translating them from TypeScript to Go.
21
+
- The change may or may not be applicable. It may have already been ported. Do not make any significant changes outside the scope of the diff. If the change cannot be applied without significant out-of-scope changes, explain why and stop working.
22
+
- Tip: search for functions and identifiers from the diff to find the right location to apply edits. Some files in microsoft/TypeScript have been split into multiple.
23
+
- Tip: some changes have already been ported, like changes to diagnostic message text. Tests do not need to be ported as they are imported from the submodule.
24
+
3. Refer to your copilot_instructions.md for guidance on how to build and test your change. Note the following differences to the typical development workflow:
25
+
- Since you are porting the implementation for a behavior that already has tests in the submodule, you don't need to add new tests. Instead, your change should change existing baselines.
26
+
- If done correctly, you should see removals in `.diff` baselines. These `.diff` removals are your ultimate source of truth: your change is not correct unless diffs are reduced.
This is the codebase for a native port of the TypeScript compiler and language server.
2
+
The source directories of interest that we have are:
3
+
4
+
-`internal` - Contains the compiler and language server code.
5
+
-`_extension` - Contains a preview VS Code extension code that integrates with the language server.
6
+
-`_submodules/TypeScript` - the stable TypeScript repository, checked out at the appropriate commit.
7
+
8
+
Most of our development takes place in the `internal` directory, and most behaviors can be tested via compiler tests.
9
+
10
+
Most development on the codebase is in Go.
11
+
Standard Go commands and practices apply, but we primarily use a tool called `hereby` to build, run tests, and other tasks.
12
+
Run `npx hereby --tasks` to see all available commands.
13
+
14
+
```sh
15
+
npx hereby build # Build the tsgo binary (not required for tests)
16
+
npx hereby test# Run tests
17
+
npx hereby format # Format the code
18
+
npx hereby lint # Run linters
19
+
20
+
# To run a specific compiler test:
21
+
go test -run='TestSubmodule/<test name>' ./internal/testrunner # For pre-existing "submodule" tests in _submodules/TypeScript
22
+
go test -run='TestLocal/<test name>' ./internal/testrunner # For new "local" tests created in testdata/tests/cases
23
+
```
24
+
25
+
Always make sure code is formatted, linted, and tested before sending a pull request.
26
+
27
+
## Compiler Features, Fixes, and Tests
28
+
29
+
When fixing a bug or implementing a new feature, at least one minimal test case should always be added in advance to verify the fix.
30
+
This project primarily uses snapshot/baseline/golden tests rather than unit tests.
31
+
New compiler tests are written in `.ts`/`.tsx` files in the directory `testdata/tests/cases/compiler/`, and are written in the following format:
32
+
33
+
**Note:** Issues with editor features cannot be tested with compiler tests in `testdata/tests/cases/`. Editor functionality requires integration testing with the language server.
34
+
35
+
```ts
36
+
// @target: esnext
37
+
// @module: preserve
38
+
// @moduleResolution: bundler
39
+
// @strict: true
40
+
// @checkJs: true
41
+
42
+
// @filename: fileA.ts
43
+
44
+
exportinterfacePerson {
45
+
name:string;
46
+
age:number;
47
+
}
48
+
49
+
// @filename: fileB.js
50
+
51
+
/**@import { Person } from "./fileA" */
52
+
53
+
/**
54
+
* @param{Person}person
55
+
*/
56
+
function greet(person) {
57
+
console.log(`Hello, ${person.name}!`);
58
+
}
59
+
```
60
+
61
+
**New compiler tests should always enable strict mode (`@strict: true`) unless the bug specifically involves non-strict mode behavior.**
62
+
63
+
Tests don't always need the above `@option`s specified, but they are common to specify or modify.
64
+
Tests can be run with multiple settings for a given option by using a comma-separated list (e.g. `@option: settingA,settingB`).
65
+
`@filename` is only required when a test has multiple files, or when writing a test for a single JavaScript file (where `allowJs` or `checkJs` is enabled).
66
+
You can see more tests in `_submodules/TypeScript/tests/cases/{compiler,conformance}`.
67
+
68
+
When tests are run, they will produce output files in the `testdata/baselines/local` directory.
69
+
**Test failures are fine** if they are just differences in output files.
70
+
A reduction/removal of `.diff` file baselines is **ideal** because it indicates the port has converged in behavior with the stable TypeScript codebase.
71
+
The new outputs can be diffed against `testdata/baselines/reference` to see if the output has changed.
72
+
73
+
Running
74
+
75
+
```sh
76
+
npx hereby baseline-accept
77
+
```
78
+
79
+
will update the baselines/snapshots, and `git diff` can be used to see what has changed.
80
+
81
+
It is ideal to implement features and fixes in the following order, and commit code after each step:
82
+
83
+
1. Write a minimal test case, or test cases, that demonstrate the bug or feature.
84
+
1. Run the tests to ensure it fails (for a bug) or passes (for a feature). Then accept generated baselines (not applicable in the case of a crash).
85
+
1. Implement the fix or feature.
86
+
1. Run the tests again to ensure everything is working correctly. Accept the baselines.
87
+
88
+
It is fine to implement more and more of a feature across commits, but be sure to update baselines every time so that reviewers can measure progress.
89
+
90
+
## Code Porting Reference
91
+
92
+
The code in `internal` is ported from the code in `_submodules/TypeScript`.
93
+
When implementing features or fixing bugs, those files should be searched for similar functions when code is either missing or potentially wrong.
94
+
The TypeScript submodule serves as the reference implementation for behavior and functionality.
95
+
96
+
# Other Instructions
97
+
98
+
- Do not add or change existing dependencies unless asked to.
0 commit comments