Merge pull request #242 from microsoft/learn

Update the wiki to use the right links and offer some better advice about how to debug the wiki

Author: Orta

.github/workflows/sync.yml

@@ -22,7 +22,7 @@ jobs:
       # Update search links from the origin repo before pushing to the upstream
       - run: git clone --depth 1 https://github.com/microsoft/TypeScript.git
       - run: npm i
-      - run: node scripts/convertRelativeLinksToHardcoded.js **/*.md --write
+      - run: node scripts/convertRelativeLinksToHardcoded.js "**/*.md" --write
       - run: rm -rf TypeScript
 
       - run: git add .

README.md

@@ -20,6 +20,16 @@ Then you can open: `http://localhost:4567`
 
 Things to remember:
 
+- Gollum is a bit of a nightmare for testing, my current technique is:
+
+  ```sh
+  # before
+  git branch -b thing_i_am_working_on
+  
+  # to iterate, amend the commit and re-run gollum against that bit of git
+  git add .; git commit --amend --no-edit --no-verify; gollum --ref thing_i_am_working_on
+  ```
+
 - Wikis don't support nesting, so filenames have to get a bit wild
 
   ```diff

compiler/codebase/screenshots/threeslash-refs.png

@@ -17,9 +17,9 @@ This function takes a few params:
 const a = "Hello World";
 ```
 
-  <!-- prettier-ignore-start -->
+<!-- prettier-ignore-start -->
 
 [0]: <src/compiler/checker.ts - function inferTypes(>
 [1]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html#strict-function-types
 
-  <!-- prettier-ignore-end -->
+<!-- prettier-ignore-end -->

compiler/codebase/src/services/formatting.md

@@ -1,4 +1,4 @@
-This page follows on from [README.md](./README.md).
+This page follows on from [[Learn the Compiler|learn-the-compiler]].
 
 ### Getting set up
 
@@ -30,8 +30,10 @@ You'll probably want to add the following to your watch section in VS Code:
 This is really useful for keeping track of changing state, and it's pretty often that those are the names of
 things you're looking for.
 
+If you want to see what a debugging session looks like with the compiler team, watch [these](https://www.youtube.com/watch?v=3vwO4DwlGYE) [videos](https://www.youtube.com/watch?v=Xq4p5LXaO8Y).
+
 ### Getting started
 
-You can learn about the different ways to [write a test here](./systems/testing) to try and re-produce a bug. It
+You can learn about the different ways to [[write a test here|systems-testing]] to try and re-produce a bug. It
 might be a good idea to look in the recently closed PRs to find something small which adds a test case, then read
 the test and the code changes to get used to the flow.

compiler/systems/testing/screenshots/diff.png

@@ -21,7 +21,8 @@ code .
 gulp runtests-parallel
 ```
 
-To dive deeper into getting set up to work on the codebase, read [the CONTRIBUTING.md](./CONTRIBUTING.md).
+
+To dive deeper into getting set up to work on the codebase, read: [[Getting Set Up|getting-started-with-the-compiler]].
 
 ### Critical prior knowledge
 

compiler/systems/testing/units.md

@@ -1,14 +1,15 @@
 # Baselines
 
-Baseline tests are effectively large folder-based snapshot tests. Like [fourslash](./fourslash), these tests are
+Baseline tests are effectively large folder-based snapshot tests. Like [[Baselines|systems-fourslash]], these tests are
 somewhat integration level. These test generally test the internals of the compiler, they do this by you creating
 a TypeScript file where the snapshot result is a symbol map of all the symbols in that file and a list of all
 raised errors then compiling the tests.
 
 ### How to make a baseline
 
-1. Make a new file: ` touch tests/cases/compiler/overloadFunctionsNotEqualToGenerics.ts`. Add some TypeScript to it.
-2. d
+1. Make a new file: ` touch tests/cases/compiler/overloadFunctionsNotEqualToGenerics.ts`. 
+1. Add some TypeScript to it.
+1. Run run your test in 
 
 
 ### How to amend a baseline
@@ -29,13 +30,8 @@ tests/baselines/local/
 ```
 
 This lets you know that two tests have changed from what you expect. They live in `local/api`, so you can compare
-the folders. I normally use [Kaleidoscope](https://www.kaleidoscopeapp.com), but the team loves 
-[Beyond Compare](https://scootersoftware.com) - it's a bit Windows-y but does a good job showing you how the 
+the folders. The team loves [Beyond Compare](https://scootersoftware.com) - it does a good job showing you how the 
 folder infrastructure differs.
 
-![./screenshots/diff.png](./screenshots/diff.png)
-
-
-
 Once you're happy with the new baselines, you can run `gulp baseline-accept` to move them into the codebase. 
 You will be able to see your diffs in git now. :+1:

compiler/GLOSSARY.md renamed to learn/compiler-glossary.md

@@ -17,7 +17,7 @@ const errors: Diagnostic[] = [];
 Then it starts If the letter is a - then start looking forwards to see if the arg is available in [the
 optionmap][4]
 
-[0]: src/tsc/tsc.ts
+[0]: https://github.com/microsoft/TypeScript/blob/master/src/tsc/tsc.ts
 [1]: <src/tsc/tsc.ts - function executeCommandLine>
 [2]: <src/compiler/types.ts - export interface ParsedCommandLine>
 [3]: <src/compiler/commandLineParser.ts - function parseCommandLineWorker>

compiler/codebase/src/compiler/checker-inferrence.md renamed to learn/compiler/compiler-checker-inferrence.md

@@ -32,8 +32,6 @@ requests a set of rules which can be applied to the items via `createRulesMap`.
 There are a lot of rules, which you can find in [rules.ts](./rules.ts) each one has a left and right reference to
 nodes or token ranges and note of what action should be applied by the formatter.
 
-## Rules
-
 ### Where is this used?
 
 The formatter is used mainly from any language service operation that inserts or modifies code. The formatter is

compiler/codebase/src/compiler/checker.md renamed to learn/compiler/compiler-checker.md

@@ -53,10 +53,10 @@ moment;`
 ### Formatting
 
 <!-- prettier-ignore-start -->
-[0]: /src/testRunner/fourslashRunner.ts
-[1]: /tests/cases/fourslash
-[2]: /src/testRunner/runner.ts
-[3]: /src/harness/fourslash.ts
+[0]: https://github.com/microsoft/TypeScript/blob/master/src/testRunner/fourslashRunner.ts
+[1]: https://github.com/microsoft/TypeScript/blob/master/tests/cases/fourslash
+[2]: https://github.com/microsoft/TypeScript/blob/master/src/testRunner/runner.ts
+[3]: https://github.com/microsoft/TypeScript/blob/master/src/harness/fourslash.ts
 [4]: <src/harness/fourslash.ts - function runFourSlashTest(>
 [5]: <src/harness/fourslash.ts - function runFourSlashTestContent(>
 [5]: <src/harness/fourslash.ts - function parseTestData(>

compiler/codebase/src/compiler/emitter.md renamed to learn/compiler/compiler-emitter.md

@@ -2,9 +2,8 @@
 
 Yep, TypeScript has tests. Quite a lot, with a few different techniques:
 
-- [Unit Tests](./units.md)
-- [Baselines](./baselines.md)
-- [Fourslash](./fourslash.md)
+- [[Baselines|systems-baselines]]
+- [[Fourslash|systems-fourslash]]
 
 ## Commands worth knowing
 

compiler/codebase/src/compiler/parser.md renamed to learn/compiler/compiler-parser.md

@@ -14,5 +14,4 @@ VS Code has three extensions related to TypeScript:
 A large amount of the work happens in the [`TypeScriptServiceClient`][1] which is the VS Code side of the
 TSServer.
 
-[1]:
-  https://github.com/microsoft/vscode/blob/master/extensions/typescript-language-features/src/typescriptServiceClient.ts#L75
+[1]: https://github.com/microsoft/vscode/blob/master/extensions/typescript-language-features/src/typescriptServiceClient.ts#L75

compiler/codebase/src/compiler/scanner.md renamed to learn/compiler/compiler-scanner.md

@@ -2,7 +2,8 @@
   "dependencies": {
     "markdown-magic": "^1.0.0",
     "typescript": "latest",
-    "glob": "^7.1.6"
+    "glob": "^7.1.6",
+    "escape-regex-string": "^1.0.6"
   },
   "scripts": {
     "build": "md-magic --path '**/*.md'",

compiler/codebase/src/compiler/types.md renamed to learn/compiler/compiler-types.md

@@ -16,6 +16,7 @@ const glob = require("glob")
 const {readFileSync, writeFileSync, existsSync}  = require("fs")
 const {join}  = require("path")
 const { execSync } = require("child_process");
+const escapeRegex = require("escape-regex-string");
 
 if (!process.argv[2]) throw new Error("Did not include a glob for markdown files to change")
 
@@ -45,7 +46,7 @@ files.forEach(file => {
     const originalFile = readFileSync(join(repoPath, file), "utf8")
     if (!originalFile) throw new Error(`Could not find a file at '${join(repoPath, file)}'`)
 
-    const line = getLineNo(originalFile, new RegExp(searchTerm))
+    const line = getLineNo(originalFile, new RegExp(escapeRegex(searchTerm)))
     const lineRef = line && line[0] && line[0].number ? `#L${line[0].number}`: ""
     const replacement = `: https://github.com/microsoft/TypeScript/blob/${repoHead.trim()}/${file}${lineRef}`
     content = content.replace(original, replacement)