Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: fully onboard to create #1839

Open
wants to merge 34 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
facffb5
feat: fully onboard to create
JoshuaKGoldberg Jan 13, 2025
6ec87e6
Use create-fs intakeFromDirectory and create-testers diffCreatedDirec…
JoshuaKGoldberg Jan 14, 2025
b62862a
alpha.13
JoshuaKGoldberg Jan 14, 2025
f7ca5ad
Merge branch 'main'
JoshuaKGoldberg Jan 14, 2025
2a2932c
Update pnpm-lock.yaml
JoshuaKGoldberg Jan 14, 2025
1f50a82
Merge branch 'main' into create-its-happening
JoshuaKGoldberg Jan 14, 2025
c835c97
test: smaller lines in docs.test.ts
JoshuaKGoldberg Jan 14, 2025
580d1bb
Merge branch 'main'
JoshuaKGoldberg Jan 15, 2025
323f007
Merge branch 'main'
JoshuaKGoldberg Jan 15, 2025
06f0aaa
Small diff cleanups
JoshuaKGoldberg Jan 15, 2025
e25252c
Merge branch 'main'
JoshuaKGoldberg Jan 15, 2025
5f80300
Merge branch 'main'
JoshuaKGoldberg Jan 15, 2025
62eae88
Merge branch 'main' into create-its-happening
JoshuaKGoldberg Jan 15, 2025
c4625dd
update integration snapshot for knip fix
JoshuaKGoldberg Jan 15, 2025
04c3c74
update integration snapshot for eslint newline removal
JoshuaKGoldberg Jan 15, 2025
c5e9a79
Merge branch 'main' into create-its-happening
JoshuaKGoldberg Jan 15, 2025
82ed2c1
Merge branch 'main'
JoshuaKGoldberg Jan 15, 2025
8422754
fix: blockAllContributors table needs to also disable cspell
JoshuaKGoldberg Jan 15, 2025
0820495
Merge branch 'main' into create-its-happening
JoshuaKGoldberg Jan 15, 2025
158010b
add CODECOV_TOKEN to integration test
JoshuaKGoldberg Jan 15, 2025
37dfd6c
Merge branch 'main' into create-its-happening
JoshuaKGoldberg Jan 15, 2025
d522c6b
Merge branch 'main'
JoshuaKGoldberg Jan 15, 2025
c3af521
docs: add missing Codecov to Blocks.md
JoshuaKGoldberg Jan 15, 2025
1fcff5f
bump get-github-auth-token to avoid crash
JoshuaKGoldberg Jan 15, 2025
5f5676a
Switch pre-commit file mode: ... to executable: true
JoshuaKGoldberg Jan 15, 2025
a727c5e
Merge branch 'main' into create-its-happening
JoshuaKGoldberg Jan 15, 2025
3717ae8
Merge branch 'main'
JoshuaKGoldberg Jan 15, 2025
a68b0c5
Assorted docs touchups
JoshuaKGoldberg Jan 15, 2025
3b82fed
More docs touchups, around blocks and options
JoshuaKGoldberg Jan 15, 2025
e8f76ae
fix: pipe GH Actions CI jobs addons to ruleset contexts
JoshuaKGoldberg Jan 15, 2025
24fba7e
fix: blockPackageJson correct pnpm install --offline... ugh.
JoshuaKGoldberg Jan 15, 2025
6461599
Remove other test package.json dependencies in blockVitest
JoshuaKGoldberg Jan 15, 2025
a98eec3
fix: silent scripts
JoshuaKGoldberg Jan 15, 2025
d89754f
fix: remove-dependencies/bin/index.js
JoshuaKGoldberg Jan 15, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
165 changes: 1 addition & 164 deletions .github/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo) and [installing pnpm](https://pnpm.io/installation):

```shell
git clone https://github.com/ < your-name-here > /create-typescript-app
git clone https://github.com/(your-name-here)/create-typescript-app
JoshuaKGoldberg marked this conversation as resolved.
Show resolved Hide resolved
cd create-typescript-app
pnpm install
```
Expand Down Expand Up @@ -104,166 +104,3 @@ Add `--watch` to keep the type checker running in a watch mode that updates the
```shell
pnpm tsc --watch
```

## Setup Scripts

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.

Each follows roughly the same general flow:

1. `bin/index.ts` uses `bin/mode.ts` to determine which of the three setup scripts to run
2. `readOptions` parses in options from local files, Git commands, npm APIs, and/or files on disk
3. `runOrRestore` wraps the setup script's main logic in a friendly prompt wrapper
4. The setup script wraps each portion of its main logic with `withSpinner`
- Each step of setup logic is generally imported from within `src/steps`
5. A call to `outro` summarizes the results for the user

> **Warning**
> Each setup script overrides many files in the directory they're run in.
> Make sure to save any changes you want to preserve before running them.

### The Creation Script

> 📝 See [`docs/Creation.md`](../docs/Creation.md) for user documentation on the creation script.

This template's "creation" script is located in `src/create/`.
You can run it locally with `node bin/index.js --mode create`.
Note that files need to be built with `pnpm run build` beforehand.

#### Testing the Creation Script

You can run the end-to-end test for creation locally on the command-line.
Note that the files need to be built with `pnpm run build` beforehand.

```shell
pnpm run test:create
```

That end-to-end test executes `script/create-test-e2e.ts`, which:

1. Runs the creation script to create a new `test-repository` child directory and repository, capturing code coverage
2. Asserts that commands such as `build` and `lint` each pass

The `pnpm run test:create` script is run in CI to ensure that templating changes are in sync with the template's actual files.
See `.github/workflows/ci.yml`'s `test_creation_script` job.

### The Initialization Script

> 📝 See [`docs/Initialization.md`](../docs/Initialization.md) for user documentation on the initialization script.

This template's "initialization" script is located in `src/initialize/`.
You can run it locally with `pnpm run initialize`.
It uses [`tsx`](https://github.com/esbuild-kit/tsx) so you don't need to build files before running.

```shell
pnpm run initialize
```

#### Testing the Initialization Script

You can run the end-to-end test for initializing locally on the command-line.
Note that files need to be built with `pnpm run build` beforehand.

```shell
pnpm run test:initialize
```

That end-to-end test executes `script/initialize-test-e2e.ts`, which:

1. Runs the initialization script using `--skip-github-api` and other skip flags
2. Checks that the local repository's files were changed correctly (e.g. removed initialization-only files)
3. Runs `pnpm run lint:knip` to make sure no excess dependencies or files were left over
4. Resets everything
5. Runs initialization a second time, capturing test coverage

The `pnpm run test:initialize` script is run in CI to ensure that templating changes are in sync with the template's actual files.
See `.github/workflows/ci.yml`'s `test_initialization_script` job.

### The Migration Script

> 📝 See [`docs/Migration.md`](../docs/Migration.md) for user documentation on the migration script.

This template's "migration" script is located in `src/migrate/`.
Note that files need to be built with `pnpm run build` beforehand.

To test out the script locally, run it from a different repository's directory:

```shell
cd ../other-repo
node ../create-typescript-app/bin/migrate.js
```

The migration script will work on any directory.
You can try it out in a blank directory with scripts like:

```shell
cd ..
mkdir temp
cd temp
node ../create-typescript-app/bin/migrate.js
```

#### Testing the Migration Script

> 💡 Seeing `Oh no! Running the migrate script unexpectedly modified:` errors?
> _[Unexpected File Modifications](#unexpected-file-modifications)_ covers that below.

You can run the end-to-end test for migrating locally on the command-line:

```shell
pnpm run test:migrate
```

That end-to-end test executes `script/migrate-test-e2e.ts`, which:

1. Runs the migration script using `--skip-github-api` and other skip flags, capturing code coverage
2. Checks that only a small list of allowed files were changed
3. Checks that the local repository's files were changed correctly (e.g. removed initialization-only files)

The `pnpm run test:migrate` script is run in CI to ensure that templating changes are in sync with the template's actual files.
See `.github/workflows/ci.yml`'s `test_migration_script` job.

> Tip: if the migration test is failing in CI and you don't see any errors, try [downloading the full logs](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#downloading-logs).

##### Migration Snapshot Failures

The migration test uses the [Vitest file snapshot](https://vitest.dev/guide/snapshot#file-snapshots) in `script/__snapshots__/migrate-test-e2e.ts.snap` to store expected differences to this repository after running the migration script.
The end-to-end migration test will fail any changes that don't keep the same differences in that snapshot.

You can update the snapshot file by:

1. Committing any changes to your local repository
2. Running `pnpm i` and `pnpm build` if any updates have been made to the `package.json` or `src/` files, respectively
3. Running `pnpm run test:migrate -u` to update the snapshot

At this point there will be some files changed:

- `script/__snapshots__/migrate-test-e2e.ts.snap` will have updates if any files mismatched templates
- The actual updated files on disk will be there too

If the snapshot file changes are what you expected, then you can commit them.
The rest of the file changes can be reverted.

> [🚀 Feature: Add a way to apply known file changes after migration #1184](https://github.com/JoshuaKGoldberg/create-typescript-app/issues/1184) tracks turning the test snapshot into a feature.

##### Unexpected File Modifications

The migration test also asserts that no files were unexpectedly changed.
If you see a failure like:

```plaintext
Oh no! Running the migrate script unexpectedly modified:
- ...
```

...then that means the file generated from templates differs from what's checked into the repository.
This is most often caused by changes to templates not being applied to checked-in files too.

Templates for files are generally stored in [`src/steps/writing/creation`] under a path roughly corresponding to the file they describe.
For example, the template for `tsup.config.ts` is stored in [`src/steps/writing/creation/createTsupConfig.ts`](../src/steps/writing/creation/createTsupConfig.ts).
If the `createTsupConfig` function were to be modified without an equivalent change to `tsup.config.ts` -or vice-versa- then the migration test would report:

```plaintext
Oh no! Running the migrate script unexpectedly modified:
- tsup.config.ts
```
5 changes: 0 additions & 5 deletions .github/codecov.yml

This file was deleted.

47 changes: 0 additions & 47 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -69,53 +69,6 @@ jobs:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
if: always()
uses: codecov/codecov-action@v3
with:
flags: unit
test_creation_script:
name: Test Creation Script
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/prepare
- run: pnpm run build
- run: pnpm run test:create
- env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
if: always()
uses: codecov/codecov-action@v3
with:
files: coverage-create/lcov.info
flags: create
test_initialization_script:
name: Test Initialization Script
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/prepare
- run: pnpm run build
- run: pnpm run test:initialize
- env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
if: always()
uses: codecov/codecov-action@v3
with:
files: coverage-initialize/lcov.info
flags: initialize
test_migration_script:
name: Test Migration Script
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/prepare
- run: pnpm run build
- run: pnpm run test:migrate
- env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
if: always()
uses: codecov/codecov-action@v3
with:
files: coverage-migrate/lcov.info
flags: migrate
type_check:
name: Type Check
runs-on: ubuntu-latest
Expand Down
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
/coverage*
/coverage
/lib
/node_modules
2 changes: 1 addition & 1 deletion .prettierignore
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/.husky
/coverage*
/coverage
/lib
/pnpm-lock.yaml
Loading
Loading