Skip to content

Commit

Permalink
feat: initialized repo ✨
Browse files Browse the repository at this point in the history
  • Loading branch information
JoshuaKGoldberg committed Mar 2, 2024
1 parent 551eb51 commit 8693bed
Show file tree
Hide file tree
Showing 196 changed files with 208 additions and 17,433 deletions.
468 changes: 21 additions & 447 deletions .all-contributorsrc

Large diffs are not rendered by default.

10 changes: 0 additions & 10 deletions .eslintrc.cjs
Original file line number Diff line number Diff line change
@@ -1,13 +1,3 @@
/*
👋 Hi! This ESLint configuration contains a lot more stuff than many repos'!
You can read from it to see all sorts of linting goodness, but don't worry -
it's not something you need to exhaustively understand immediately. 💙
If you're interested in learning more, see the 'getting started' docs on:
- ESLint: https://eslint.org
- typescript-eslint: https://typescript-eslint.io
*/

/** @type {import("@types/eslint").Linter.Config} */
module.exports = {
env: {
Expand Down
10 changes: 5 additions & 5 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing

Thanks for your interest in contributing to `create-typescript-app`! 💖
Thanks for your interest in contributing to `github-notifications-prune`! 💖

> After this page, see [DEVELOPMENT.md](./DEVELOPMENT.md) for local development instructions.
Expand All @@ -10,7 +10,7 @@ This project contains a [Contributor Covenant code of conduct](./CODE_OF_CONDUCT

## Reporting Issues

Please do [report an issue on the issue tracker](https://github.com/JoshuaKGoldberg/create-typescript-app/issues/new/choose) if there's any bugfix, documentation improvement, or general enhancement you'd like to see in the repository! Please fully fill out all required fields in the most appropriate issue form.
Please do [report an issue on the issue tracker](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues/new/choose) if there's any bugfix, documentation improvement, or general enhancement you'd like to see in the repository! Please fully fill out all required fields in the most appropriate issue form.

## Sending Contributions

Expand All @@ -22,8 +22,8 @@ There are two steps involved:

### Finding an Issue

With the exception of very small typos, all changes to this repository generally need to correspond to an [unassigned open issue marked as `status: accepting prs` on the issue tracker](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+accepting+prs%22+no%3Aassignee+).
If this is your first time contributing, consider searching for [unassigned issues that also have the `good first issue` label](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3A%22status%3A+accepting+prs%22+no%3Aassignee+).
With the exception of very small typos, all changes to this repository generally need to correspond to an [unassigned open issue marked as `status: accepting prs` on the issue tracker](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+accepting+prs%22+no%3Aassignee+).
If this is your first time contributing, consider searching for [unassigned issues that also have the `good first issue` label](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3A%22status%3A+accepting+prs%22+no%3Aassignee+).
If the issue you'd like to fix isn't found on the issue, see [Reporting Issues](#reporting-issues) for filing your own (please do!).

#### Issue Claiming
Expand All @@ -42,7 +42,7 @@ Be sure to fill out the pull request template's requested information -- otherwi
PRs are also expected to have a title that adheres to [conventional commits](https://www.conventionalcommits.org/en/v1.0.0).
Only PR titles need to be in that format, not individual commits.
Don't worry if you get this wrong: you can always change the PR title after sending it.
Check [previously merged PRs](https://github.com/JoshuaKGoldberg/create-typescript-app/pulls?q=is%3Apr+is%3Amerged+-label%3Adependencies+) for reference.
Check [previously merged PRs](https://github.com/JoshuaKGoldberg/github-notifications-prune/pulls?q=is%3Apr+is%3Amerged+-label%3Adependencies+) for reference.

#### Draft PRs

Expand Down
169 changes: 3 additions & 166 deletions .github/DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Development

> If you'd like a more guided walkthrough, see [Contributing to a create-typescript-app Repository](https://www.joshuakgoldberg.com/blog/contributing-to-a-create-typescript-app-repository).
> If you'd like a more guided walkthrough, see [Contributing to a github-notifications-prune Repository](https://www.joshuakgoldberg.com/blog/contributing-to-a-github-notifications-prune-repository).
> It'll walk you through the common activities you'll need to contribute.
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
cd create-typescript-app
git clone https://github.com/<your-name-here>/github-notifications-prune
cd github-notifications-prune
pnpm install
```

Expand Down Expand Up @@ -111,166 +111,3 @@ To debug a unit test, open a test file, then run _Debug Current Test File_ from
### `bin` Apps

To debug a `bin` app, add a breakpoint to your code, then run _Debug Program_ from the VS Code Debug panel (or press F5).

## 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.js`, 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/test-create.yml`.

### 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.js`, 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/test-initialize.yml`.

### 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.js`, 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/test-migrate.yml`.

> 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.js.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.js.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
```
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!-- Note: Please must use one of our issue templates to file an issue! 🛑 -->
<!-- 👉 https://github.com/JoshuaKGoldberg/create-typescript-app/issues/new/choose 👈 -->
<!-- 👉 https://github.com/JoshuaKGoldberg/github-notifications-prune/issues/new/choose 👈 -->
<!-- **Issues that should have been filed with a template will be closed without action, and we will ask you to use a template.** -->

<!-- This blank issue template is only for issues that don't fit any of the templates. -->
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/01-bug.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ body:
required: true
- label: I have pulled the latest `main` branch of the repository.
required: true
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aissue) and found none that matched my issue.
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues?q=is%3Aissue) and found none that matched my issue.
required: true
type: checkboxes
- attributes:
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/02-documentation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ body:
options:
- label: I have pulled the latest `main` branch of the repository.
required: true
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aissue) and found none that matched my issue.
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues?q=is%3Aissue) and found none that matched my issue.
required: true
type: checkboxes
- attributes:
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/03-feature.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ body:
options:
- label: I have pulled the latest `main` branch of the repository.
required: true
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aissue) and found none that matched my issue.
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues?q=is%3Aissue) and found none that matched my issue.
required: true
type: checkboxes
- attributes:
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/04-tooling.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ body:
required: true
- label: I have pulled the latest `main` branch of the repository.
required: true
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aissue) and found none that matched my issue.
- label: I have [searched for related issues](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues?q=is%3Aissue) and found none that matched my issue.
required: true
type: checkboxes
- attributes:
Expand Down
6 changes: 3 additions & 3 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<!-- 👋 Hi, thanks for sending a PR to create-typescript-app! 💖.
<!-- 👋 Hi, thanks for sending a PR to github-notifications-prune! 💖.
Please fill out all fields below and make sure each item is true and [x] checked.
Otherwise we may not be able to review your PR. -->

## PR Checklist

- [ ] Addresses an existing open issue: fixes #000
- [ ] 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)
- [ ] Steps in [CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md) were taken
- [ ] That issue was marked as [`status: accepting prs`](https://github.com/JoshuaKGoldberg/github-notifications-prune/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [ ] Steps in [CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/github-notifications-prune/blob/main/.github/CONTRIBUTING.md) were taken

## Overview

Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/post-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ jobs:
The release is available on:
* [GitHub releases](https://github.com/JoshuaKGoldberg/create-typescript-app/releases/tag/{release_tag})
* [npm package (@latest dist-tag)](https://www.npmjs.com/package/create-typescript-app/v/${{ env.npm_version }})
* [GitHub releases](https://github.com/JoshuaKGoldberg/github-notifications-prune/releases/tag/{release_tag})
* [npm package (@latest dist-tag)](https://www.npmjs.com/package/github-notifications-prune/v/${{ env.npm_version }})
Cheers! 📦🚀
Expand Down
27 changes: 0 additions & 27 deletions .github/workflows/test-initialize.yml

This file was deleted.

27 changes: 0 additions & 27 deletions .github/workflows/test-migrate.yml

This file was deleted.

Loading

0 comments on commit 8693bed

Please sign in to comment.