Skip to content

Commit 9f14f47

Browse files
docs: streamlined and organized DEVELOPMENT.md (#1735)
## PR Checklist - [x] Addresses an existing open issue: fixes #1710 - [x] That issue was marked as [`status: accepting prs`](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) - [x] Steps in [CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md) were taken ## Overview Mostly re-applies changes from #1670. 💖
1 parent 1094f0f commit 9f14f47

File tree

4 files changed

+61
-42
lines changed

4 files changed

+61
-42
lines changed

.github/DEVELOPMENT.md

+7-14
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ Add `--watch` to run the builder in a watch mode that continuously cleans and re
2828
pnpm build --watch
2929
```
3030

31+
### Built App Debugging
32+
33+
This repository includes a [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging) for debugging.
34+
To debug a `bin` app, add a breakpoint to your code, then run _Debug Program_ from the VS Code Debug panel (or press F5).
35+
VS Code will automatically run the `build` task in the background before running `./bin/index.js`.
36+
3137
## Formatting
3238

3339
[Prettier](https://prettier.io) is used to format code.
@@ -58,7 +64,7 @@ For example, ESLint can be run with `--fix` to auto-fix some lint rule complaint
5864
pnpm run lint --fix
5965
```
6066

61-
Note that you'll likely need to run `pnpm build` before `pnpm lint` so that lint rules which check the file system can pick up on any built files.
67+
Note that you'll need to run `pnpm build` before `pnpm lint` so that lint rules which check the file system can pick up on any built files.
6268

6369
## Testing
6470

@@ -99,19 +105,6 @@ Add `--watch` to keep the type checker running in a watch mode that updates the
99105
pnpm tsc --watch
100106
```
101107

102-
## Debugging
103-
104-
This repository includes a [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging) for debugging.
105-
Depending upon the type of usage, it can include debugging for unit tests _and_ for executable (or "bin") apps.
106-
107-
### Unit Tests
108-
109-
To debug a unit test, open a test file, then run _Debug Current Test File_ from the VS Code Debug panel (or press F5).
110-
111-
### `bin` Apps
112-
113-
To debug a `bin` app, add a breakpoint to your code, then run _Debug Program_ from the VS Code Debug panel (or press F5).
114-
115108
## Setup Scripts
116109

117110
As described in the `README.md` file and `docs/`, this template repository comes with three scripts that can set up an existing or new repository.

script/__snapshots__/migrate-test-e2e.ts.snap

+1-3
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,7 @@ exports[`expected file changes > cspell.json 1`] = `
132132
"markdownlintignore",
133133
"mtfoley",
134134
"npmignore",
135-
- "npmpackagejsonlintrc",
136-
"outro",
137-
- "packagejson",
135+
@@ ... @@
138136
"tada",
139137
"tseslint",
140138
"tsup",

src/steps/writing/creation/dotGitHub/createDevelopment/index.test.ts

+16-6
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ describe("createDevelopment", () => {
8787
8888
- \`pnpm lint\` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files
8989
- \`pnpm lint:knip\` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports
90-
- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint): Checks Markdown source files
90+
- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files
9191
- \`pnpm lint:packages\` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the \`pnpm-lock.yml\` file
9292
- \`pnpm lint:spelling\` ([cspell](https://cspell.org)): Spell checks across all source files
9393
@@ -99,7 +99,7 @@ describe("createDevelopment", () => {
9999
pnpm run lint --fix
100100
\`\`\`
101101
102-
Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.
102+
Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.
103103
104104
## Testing
105105
@@ -216,7 +216,7 @@ describe("createDevelopment", () => {
216216
pnpm run lint --fix
217217
\`\`\`
218218
219-
Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.
219+
Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.
220220
221221
## Testing
222222
@@ -303,7 +303,17 @@ Def 456.
303303
304304
## Building
305305
306-
Will be removed.
306+
Run [**tsup**](https://tsup.egoist.dev) locally to build source files from \`src/\` into output files in \`lib/\`:
307+
308+
\`\`\`shell
309+
pnpm build
310+
\`\`\`
311+
312+
Add \`--watch\` to run the builder in a watch mode that continuously cleans and recreates \`lib/\` as you save files:
313+
314+
\`\`\`shell
315+
pnpm build --watch
316+
\`\`\`
307317
308318
## Formatting
309319
@@ -323,7 +333,7 @@ Def 456.
323333
324334
- \`pnpm lint\` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files
325335
- \`pnpm lint:knip\` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports
326-
- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint): Checks Markdown source files
336+
- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files
327337
- \`pnpm lint:packages\` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the \`pnpm-lock.yml\` file
328338
- \`pnpm lint:spelling\` ([cspell](https://cspell.org)): Spell checks across all source files
329339
@@ -335,7 +345,7 @@ Def 456.
335345
pnpm run lint --fix
336346
\`\`\`
337347
338-
Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.
348+
Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.
339349
340350
## Testing
341351

src/steps/writing/creation/dotGitHub/createDevelopment/index.ts

+37-19
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ Add \`--watch\` to run the builder in a watch mode that continuously cleans and
2626
\`\`\`shell
2727
pnpm build --watch
2828
\`\`\``,
29+
...(options.bin && {
30+
"### Built App Debugging": `This repository includes a [VS Code launch configuration](https://code.visualstudio.com/docs/editor/debugging) for debugging.
31+
To debug a \`bin\` app, add a breakpoint to your code, then run _Debug Program_ from the VS Code Debug panel (or press F5).
32+
VS Code will automatically run the \`build\` task in the background before running \`${options.bin}\`.`,
33+
}),
2934
"## Formatting": `[Prettier](https://prettier.io) is used to format code.
3035
It should be applied automatically when you save files in VS Code or make a Git commit.
3136
@@ -40,8 +45,7 @@ pnpm format --write
4045
pnpm run lint --fix
4146
\`\`\`
4247
43-
Note that you'll likely need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.`,
44-
48+
Note that you'll need to run \`pnpm build\` before \`pnpm lint\` so that lint rules which check the file system can pick up on any built files.`,
4549
...(!options.excludeTests && {
4650
"## Testing": `[Vitest](https://vitest.dev) is used for tests.
4751
You can run it locally on the command-line:
@@ -83,14 +87,35 @@ pnpm tsc --watch
8387
Object.keys(newSections).map((key) => key.replace(/^#* /, "")),
8488
]);
8589

86-
const preservedSections = Object.fromEntries(
87-
splitIntoSections(existingContents).filter(([key]) => {
88-
const keyText = key.replace(/^#* /, "");
89-
return !newSectionHeadings.has(
90-
headingAliases.get(keyText.toLowerCase()) ?? keyText,
91-
);
92-
}),
93-
);
90+
const existingSectionsSplit = splitIntoSections(existingContents);
91+
const preservedSectionsSplit = existingSectionsSplit.filter(([key]) => {
92+
const keyText = key.replace(/^#* /, "");
93+
return !newSectionHeadings.has(
94+
headingAliases.get(keyText.toLowerCase()) ?? keyText,
95+
);
96+
});
97+
const preservedSections = Object.fromEntries(preservedSectionsSplit);
98+
99+
const sectionLines: string[] = [];
100+
const seen = new Set<string>();
101+
102+
for (const sections of [newSections, preservedSections]) {
103+
for (const heading in sections) {
104+
if (seen.has(heading)) {
105+
continue;
106+
}
107+
108+
seen.add(heading);
109+
110+
// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
111+
const contents = sections[heading as keyof typeof sections]!;
112+
113+
sectionLines.push("");
114+
sectionLines.push(heading);
115+
sectionLines.push("");
116+
sectionLines.push(contents);
117+
}
118+
}
94119

95120
const result = `# Development
96121
${
@@ -111,14 +136,7 @@ pnpm install
111136
112137
> This repository includes a list of suggested VS Code extensions.
113138
> It's a good idea to use [VS Code](https://code.visualstudio.com) and accept its suggestion to install them, as they'll help with development.
114-
115-
${Object.entries({ ...newSections, ...preservedSections })
116-
.map(
117-
([heading, content]) => `${heading}
118-
119-
${content}`,
120-
)
121-
.join("\n\n")}
139+
${sectionLines.join("\n")}
122140
`;
123141

124142
return result;
@@ -129,7 +147,7 @@ function createLintingSection(options: Options) {
129147
!options.excludeLintKnip &&
130148
`- \`pnpm lint:knip\` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports`,
131149
!options.excludeLintMd &&
132-
`- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint): Checks Markdown source files`,
150+
`- \`pnpm lint:md\` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files`,
133151
!options.excludeLintPackages &&
134152
`- \`pnpm lint:packages\` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the \`pnpm-lock.yml\` file`,
135153
!options.excludeLintSpelling &&

0 commit comments

Comments
 (0)