From 954d3d6600c60d4aa8b4d65d1b13dcc71bd33764 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 25 Apr 2025 09:56:14 +0930 Subject: [PATCH 01/18] init --- CONTRIBUTING.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b3bd7f38 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +At the very minimum, it should cover: + +building/running in dev +how to test the cli locally +how to run and write tests +some style guidelines and code conventions + +Should also include details on how to run svelte-migrate locally, as pointed out by issue #494 + From 835ba9989678f7ce22af9fe6c7a780fc08f6174f Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 25 Apr 2025 10:25:48 +0930 Subject: [PATCH 02/18] skeleton and sveltekit reference --- CONTRIBUTING.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3bd7f38..ef259fde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,30 @@ +# SV Contributing Guide + +## Preparing +- install pnpm globally +- set up docker + - link to docker docs + - no sudo https://docs.docker.com/engine/install/linux-postinstall/ +- fork/clone/branch/pr process + - branch naming + +## build/run +- build locally +- dev locally + +## testing +- run tests +- how to write tests + +## styleguide +- conventions +- formatting and linting + +## svelte-migrate +- TODO: check issue #494 for further details on what is needed for svelte-migrate + + +# vv for reference only vv At the very minimum, it should cover: building/running in dev @@ -7,3 +34,153 @@ some style guidelines and code conventions Should also include details on how to run svelte-migrate locally, as pointed out by issue #494 +Requirements +- PNPM +- Docker with no sudo + +# SvelteKit Contributing Guide + +## Preparing + +This is a monorepo, meaning the repo holds multiple packages. It requires the use of [pnpm](https://pnpm.io/). You can [install pnpm](https://pnpm.io/installation) with: + +```bash +npm i -g pnpm +``` + +`pnpm` commands run in the project's root directory will run on all sub-projects. You can checkout the code and install the dependencies with: + +```bash +git clone git@github.com:sveltejs/kit.git +cd kit +pnpm install +``` + +## Testing Changes + +### Playground + +You can use the playground at [`playgrounds/basic`](./playgrounds/basic/) to experiment with your changes to SvelteKit locally. + +### Linking local changes + +If you want to test against an existing project, you can use [pnpm `overrides`](https://pnpm.io/package_json#pnpmoverrides) in that project: + +```jsonc +{ + // ... + "pnpm": { + "overrides": { + "@sveltejs/kit": "link:../path/to/svelte-kit/packages/kit", + // additionally/optional the adapter you're using + "@sveltejs/adapter-auto": "link:../path/to/svelte-kit/packages/adapter-auto" + } + } +} +``` + +### Testing PR changes + +Each pull request will be built and published via [pkg.pr.new/](https://pkg.pr.new/). You can test the change by installing the package with your PR number: + +``` +npm add https://pkg.pr.new/sveltejs/kit/@sveltejs/kit@YOUR_PR_NUMBER_GOES_HERE +``` + +## Code structure + +Entry points to be aware of are: + +- [`packages/create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte) - code that's run when you create a new project with `npx sv create` +- [`packages/package`](https://github.com/sveltejs/kit/tree/main/packages/package) - for the `svelte-package` command +- [`packages/kit/src/core`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/core) - code that's called at dev/build-time +- [`packages/kit/src/core/sync`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/core/sync) - for `svelte-kit sync`, which regenerates routing info and type definitions +- [`packages/kit/src/runtime`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/runtime) - code that's called at runtime +- [`packages/kit/src/exports/vite`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/exports/vite) - for all the Vite plugin related stuff +- [`packages/adapter-[platform]`](https://github.com/sveltejs/kit/tree/main/packages) - for the various SvelteKit-provided adapters + +## Good first issues + +If you're looking for an issue to tackle to get familiar with the codebase and test suite, the [**low hanging fruit**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22low+hanging+fruit%22) label contains issues that ought to be relatively straightforward to fix. Check to see if a PR already exists for an issue before working on it! + +Issues that have a clear solution but which _may_ be slightly more involved have the [**ready to implement**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22ready+to+implement%22) label. + +Issues with the [**soon**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+milestone%3Asoon) milestone are higher priority than issues with the [**later**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+milestone%3Alater+) label (though PRs for 'later' issues are still welcome, especially if you're affected by them). + +## Testing + +Run `pnpm test` to run the tests from all subpackages. Browser tests live in subdirectories of `packages/kit/test` such as `packages/kit/test/apps/basics`. + +You can run the tests for only a single package by first moving to that directory. E.g. `cd packages/kit`. + +For some packages you must rebuild each time before running the tests if you've made code changes. These packages have a `build` command. Packages like `packages/kit` don't require a build step. + +To run a single integration test or otherwise control the running of the tests locally see [the Playwright CLI docs](https://playwright.dev/docs/test-cli). Note that you will need to run these commands from the test project directory such as `packages/kit/test/apps/basics`. + +You can run the test server with `cd packages/kit/test/apps/basics; pnpm run dev` to hit it with your browser. The Playwright Inspector offers similar functionality. + +You may need to install some dependencies first, e.g. with `npx playwright install-deps` (which only works on Ubuntu). + +If there are tests that fail on the CI, you can retrieve the failed screenshots by going to the summary page of the CI run. You can usually find this by clicking on "Details" of the check results, clicking "Summary" at the top-left corner, and then scrolling to the bottom "Artifacts" section to download the archive. + +It is very easy to introduce flakiness in a browser test. If you try to fix the flakiness in a test, you can run it until failure to gain some confidence you've fixed the test with a command like: + +``` +npx playwright test --workers=1 --repeat-each 1000 --max-failures 1 -g "accepts a Request object" +``` + +## Working on Vite and other dependencies + +If you would like to test local changes to Vite or another dependency, you can build it and then use [`pnpm.overrides`](https://pnpm.io/package_json#pnpmoverrides). Please note that `pnpm.overrides` must be specified in the root `package.json` and you must first list the package as a dependency in the root `package.json`: + +```jsonc +{ + // ... + "dependencies": { + "vite": "^4.0.0" + }, + "pnpm": { + "overrides": { + "vite": "link:../path/to/vite/packages/vite" + } + } +} +``` + +## Documentation changes + +All documentation for SvelteKit is in the [`documentation` directory](https://github.com/sveltejs/kit/tree/main/documentation), and any improvements should be made as a Pull Request to this repository. The site itself is located in the [`sveltejs/svelte.dev` repo](https://github.com/sveltejs/svelte.dev) and can be run locally to preview changes. + +## Sending PRs + +### Coding style + +There are a few guidelines we follow: + +- Internal variables are written with `snake_case` while external APIs are written with `camelCase` +- Provide a single object as the argument to public APIs. This object can have multiple properties +- Avoid creating new test projects under `packages/kit/test/apps` but reuse an existing one when possible +- Ensure `pnpm lint` and `pnpm check` pass. You can run `pnpm format` to format the code + +To use the git hooks in the repo, which will save you from waiting for CI to tell you that you forgot to lint, run this: + +```bash +git config core.hookspath .githooks +``` + +### Generating changelogs + +For changes to be reflected in package changelogs, run `pnpm changeset` and follow the prompts. + +### Type changes + +If your PR changes the generated types of SvelteKit, run `pnpm generate:types` inside `packages/kit` and commit the new output (don't format it with Prettier!). Review the changes carefully to ensure there are no unwanted changes. If you don't commit type changes, CI will fail. + +## Releases + +The [Changesets GitHub action](https://github.com/changesets/action#with-publishing) will create and update a PR that applies changesets and publishes new versions of changed packages to npm. + +New packages will need to be published manually the first time if they are scoped to the `@sveltejs` organisation, by running this from the package directory: + +```bash +npm publish --access=public From 31cb9528f2ddfb90662be40ceb7f5941923a6735 Mon Sep 17 00:00:00 2001 From: Brett Date: Wed, 30 Apr 2025 06:11:58 +0930 Subject: [PATCH 03/18] workflow and preparing --- CONTRIBUTING.md | 53 ++++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef259fde..5eedbaa4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,35 @@ # SV Contributing Guide +## Contributing code + +We follow the standard fork-based workflow: + +1. **Fork** this repository to your GitHub account. +2. **Clone** your fork locally. +3. **Create a new branch** for your change: + `git checkout -b your-feature-name` +4. **Commit and push** your changes to your branch. +5. **Open a pull request** from your branch to the `main` branch of this repository. + +Please keep your pull requests focused to feature or issue. Focused smaller changes are easier to review and faster to merge. + ## Preparing -- install pnpm globally -- set up docker - - link to docker docs - - no sudo https://docs.docker.com/engine/install/linux-postinstall/ -- fork/clone/branch/pr process - - branch naming +This is a monorepo, meaning the repo holds multiple packages. It requires the use of [pnpm](https://pnpm.io/). You can [install pnpm](https://pnpm.io/installation) with: + +```bash +npm i -g pnpm +``` + +For running certain packages and tests locally you will need to install [docker](https://docs.docker.com/get-started/get-docker). +Linux users you will have to ensure 'sudo' is not required. See [docker post install](https://docs.docker.com/engine/install/linux-postinstall/) + +`pnpm` commands run in the project's root directory will run on all sub-projects. You can checkout the code and install the dependencies with: + +```bash +git clone git@github.com:YOUR_GITHUB_USER_HERE/cli.git +cd cli +pnpm install +``` ## build/run - build locally @@ -24,7 +47,7 @@ - TODO: check issue #494 for further details on what is needed for svelte-migrate -# vv for reference only vv +# vv REFERENCE ONLY vv At the very minimum, it should cover: building/running in dev @@ -40,22 +63,6 @@ Requirements # SvelteKit Contributing Guide -## Preparing - -This is a monorepo, meaning the repo holds multiple packages. It requires the use of [pnpm](https://pnpm.io/). You can [install pnpm](https://pnpm.io/installation) with: - -```bash -npm i -g pnpm -``` - -`pnpm` commands run in the project's root directory will run on all sub-projects. You can checkout the code and install the dependencies with: - -```bash -git clone git@github.com:sveltejs/kit.git -cd kit -pnpm install -``` - ## Testing Changes ### Playground From 8d7f3c4c0178b7d6b80e5b777d39c7edaf9c9de5 Mon Sep 17 00:00:00 2001 From: Brett Date: Thu, 1 May 2025 06:31:09 +0930 Subject: [PATCH 04/18] 1st draft --- CONTRIBUTING.md | 176 ++++++++++-------------------------------------- 1 file changed, 36 insertions(+), 140 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5eedbaa4..eb7bc52f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # SV Contributing Guide -## Contributing code +## Workflow We follow the standard fork-based workflow: @@ -21,7 +21,7 @@ npm i -g pnpm ``` For running certain packages and tests locally you will need to install [docker](https://docs.docker.com/get-started/get-docker). -Linux users you will have to ensure 'sudo' is not required. See [docker post install](https://docs.docker.com/engine/install/linux-postinstall/) +Linux users, you will have to ensure 'sudo' is not required. See [docker post install](https://docs.docker.com/engine/install/linux-postinstall/) `pnpm` commands run in the project's root directory will run on all sub-projects. You can checkout the code and install the dependencies with: @@ -32,162 +32,58 @@ pnpm install ``` ## build/run -- build locally -- dev locally +Build the project from root run 'build' script: -## testing -- run tests -- how to write tests - -## styleguide -- conventions -- formatting and linting - -## svelte-migrate -- TODO: check issue #494 for further details on what is needed for svelte-migrate - - -# vv REFERENCE ONLY vv -At the very minimum, it should cover: - -building/running in dev -how to test the cli locally -how to run and write tests -some style guidelines and code conventions - -Should also include details on how to run svelte-migrate locally, as pointed out by issue #494 - -Requirements -- PNPM -- Docker with no sudo - -# SvelteKit Contributing Guide - -## Testing Changes - -### Playground - -You can use the playground at [`playgrounds/basic`](./playgrounds/basic/) to experiment with your changes to SvelteKit locally. - -### Linking local changes - -If you want to test against an existing project, you can use [pnpm `overrides`](https://pnpm.io/package_json#pnpmoverrides) in that project: - -```jsonc -{ - // ... - "pnpm": { - "overrides": { - "@sveltejs/kit": "link:../path/to/svelte-kit/packages/kit", - // additionally/optional the adapter you're using - "@sveltejs/adapter-auto": "link:../path/to/svelte-kit/packages/adapter-auto" - } - } -} +```bash +#from root of project +pnpm build ``` +This outputs into /packages/PACKAGE/dist/. -### Testing PR changes - -Each pull request will be built and published via [pkg.pr.new/](https://pkg.pr.new/). You can test the change by installing the package with your PR number: - -``` -npm add https://pkg.pr.new/sveltejs/kit/@sveltejs/kit@YOUR_PR_NUMBER_GOES_HERE +Run the 'cli' package: +```bash +node ./packages/cli/dist/bin.js ``` -## Code structure - -Entry points to be aware of are: - -- [`packages/create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte) - code that's run when you create a new project with `npx sv create` -- [`packages/package`](https://github.com/sveltejs/kit/tree/main/packages/package) - for the `svelte-package` command -- [`packages/kit/src/core`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/core) - code that's called at dev/build-time -- [`packages/kit/src/core/sync`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/core/sync) - for `svelte-kit sync`, which regenerates routing info and type definitions -- [`packages/kit/src/runtime`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/runtime) - code that's called at runtime -- [`packages/kit/src/exports/vite`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/exports/vite) - for all the Vite plugin related stuff -- [`packages/adapter-[platform]`](https://github.com/sveltejs/kit/tree/main/packages) - for the various SvelteKit-provided adapters - -## Good first issues - -If you're looking for an issue to tackle to get familiar with the codebase and test suite, the [**low hanging fruit**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22low+hanging+fruit%22) label contains issues that ought to be relatively straightforward to fix. Check to see if a PR already exists for an issue before working on it! - -Issues that have a clear solution but which _may_ be slightly more involved have the [**ready to implement**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22ready+to+implement%22) label. - -Issues with the [**soon**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+milestone%3Asoon) milestone are higher priority than issues with the [**later**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+is%3Aopen+milestone%3Alater+) label (though PRs for 'later' issues are still welcome, especially if you're affected by them). - -## Testing - -Run `pnpm test` to run the tests from all subpackages. Browser tests live in subdirectories of `packages/kit/test` such as `packages/kit/test/apps/basics`. - -You can run the tests for only a single package by first moving to that directory. E.g. `cd packages/kit`. - -For some packages you must rebuild each time before running the tests if you've made code changes. These packages have a `build` command. Packages like `packages/kit` don't require a build step. - -To run a single integration test or otherwise control the running of the tests locally see [the Playwright CLI docs](https://playwright.dev/docs/test-cli). Note that you will need to run these commands from the test project directory such as `packages/kit/test/apps/basics`. - -You can run the test server with `cd packages/kit/test/apps/basics; pnpm run dev` to hit it with your browser. The Playwright Inspector offers similar functionality. - -You may need to install some dependencies first, e.g. with `npx playwright install-deps` (which only works on Ubuntu). - -If there are tests that fail on the CI, you can retrieve the failed screenshots by going to the summary page of the CI run. You can usually find this by clicking on "Details" of the check results, clicking "Summary" at the top-left corner, and then scrolling to the bottom "Artifacts" section to download the archive. - -It is very easy to introduce flakiness in a browser test. If you try to fix the flakiness in a test, you can run it until failure to gain some confidence you've fixed the test with a command like: - -``` -npx playwright test --workers=1 --repeat-each 1000 --max-failures 1 -g "accepts a Request object" +## testing +Run all tests: +```bash +#from root of project +pnpm test ``` -## Working on Vite and other dependencies - -If you would like to test local changes to Vite or another dependency, you can build it and then use [`pnpm.overrides`](https://pnpm.io/package_json#pnpmoverrides). Please note that `pnpm.overrides` must be specified in the root `package.json` and you must first list the package as a dependency in the root `package.json`: - -```jsonc -{ - // ... - "dependencies": { - "vite": "^4.0.0" - }, - "pnpm": { - "overrides": { - "vite": "link:../path/to/vite/packages/vite" - } - } -} +Run package specific tests by navigating to the package and running the test command. Eg: +```bash +cd packages/core/ +pnpm test ``` -## Documentation changes - -All documentation for SvelteKit is in the [`documentation` directory](https://github.com/sveltejs/kit/tree/main/documentation), and any improvements should be made as a Pull Request to this repository. The site itself is located in the [`sveltejs/svelte.dev` repo](https://github.com/sveltejs/svelte.dev) and can be run locally to preview changes. +- DIRECTION REQUIRED: how to write tests. -## Sending PRs +## styleguide ### Coding style There are a few guidelines we follow: - Internal variables are written with `snake_case` while external APIs are written with `camelCase` -- Provide a single object as the argument to public APIs. This object can have multiple properties -- Avoid creating new test projects under `packages/kit/test/apps` but reuse an existing one when possible - Ensure `pnpm lint` and `pnpm check` pass. You can run `pnpm format` to format the code - -To use the git hooks in the repo, which will save you from waiting for CI to tell you that you forgot to lint, run this: - +- linting ```bash -git config core.hookspath .githooks +#from root of project +pnpm lint +``` +- formatting +```bash +# from root of project +pnpm format +``` +- checking +```bash +# from root of project +pnpm check ``` -### Generating changelogs - -For changes to be reflected in package changelogs, run `pnpm changeset` and follow the prompts. - -### Type changes - -If your PR changes the generated types of SvelteKit, run `pnpm generate:types` inside `packages/kit` and commit the new output (don't format it with Prettier!). Review the changes carefully to ensure there are no unwanted changes. If you don't commit type changes, CI will fail. - -## Releases - -The [Changesets GitHub action](https://github.com/changesets/action#with-publishing) will create and update a PR that applies changesets and publishes new versions of changed packages to npm. - -New packages will need to be published manually the first time if they are scoped to the `@sveltejs` organisation, by running this from the package directory: +## svelte-migrate +- TODO: check issue #494 for further details on what is needed for svelte-migrate -```bash -npm publish --access=public From 77a9936c1263136de17907f51ec236ab51dc2411 Mon Sep 17 00:00:00 2001 From: Brett <100062845+brettearle@users.noreply.github.com> Date: Fri, 2 May 2025 21:52:43 +0930 Subject: [PATCH 05/18] Update CONTRIBUTING.md Co-authored-by: Manuel <30698007+manuel3108@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eb7bc52f..18ef9c95 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,7 +70,7 @@ There are a few guidelines we follow: - Ensure `pnpm lint` and `pnpm check` pass. You can run `pnpm format` to format the code - linting ```bash -#from root of project +# from root of project pnpm lint ``` - formatting From d77ad71d77b4d44519bf8b089ccc771300e00f59 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 2 May 2025 22:00:42 +0930 Subject: [PATCH 06/18] docs: update based on feedback --- CONTRIBUTING.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18ef9c95..9e8e2842 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,12 @@ This outputs into /packages/PACKAGE/dist/. Run the 'cli' package: ```bash -node ./packages/cli/dist/bin.js +pnpm sv +``` + +Run build with watch mode: +```bash +pnpm dev ``` ## testing @@ -52,10 +57,18 @@ Run all tests: pnpm test ``` + +Run tests with vitest ui: +```bash +#from root of project +pnpm test:ui +``` + + Run package specific tests by navigating to the package and running the test command. Eg: ```bash cd packages/core/ -pnpm test +pnpm test --project core # addons / create / migrate / etc. ``` - DIRECTION REQUIRED: how to write tests. @@ -66,7 +79,6 @@ pnpm test There are a few guidelines we follow: -- Internal variables are written with `snake_case` while external APIs are written with `camelCase` - Ensure `pnpm lint` and `pnpm check` pass. You can run `pnpm format` to format the code - linting ```bash From 5130a721c0e1a5abd8c1a033db658689228ec4c6 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 2 May 2025 22:26:31 +0930 Subject: [PATCH 07/18] docs: changelog added --- CONTRIBUTING.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9e8e2842..1a822da7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,5 +97,15 @@ pnpm check ``` ## svelte-migrate -- TODO: check issue #494 for further details on what is needed for svelte-migrate +To run svelte-migrate from local: +```bash +# from root of project +node ./packages/migrate/bin.js +``` +## Generating changelogs +For changes to be reflected in package changelogs: +```bash +# from root of project +pnpm changeset:publish +``` From 12683090ec90674107096eff6868a7fc69a57a79 Mon Sep 17 00:00:00 2001 From: Brett Date: Fri, 2 May 2025 22:32:39 +0930 Subject: [PATCH 08/18] docs: added change set directions for sv and svelte-migrate only --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a822da7..b8812a9e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,6 +104,7 @@ node ./packages/migrate/bin.js ``` ## Generating changelogs +Only publish a change set if it is in 'sv' or 'svelte-migrate' as all other packages are bundled. For changes to be reflected in package changelogs: ```bash # from root of project From 7ece3eb1d6dd58227b1a3520177d6ec49f7f219f Mon Sep 17 00:00:00 2001 From: Brett Date: Sat, 3 May 2025 00:00:25 +0930 Subject: [PATCH 09/18] docs: removed cd to packages in specific tests --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8812a9e..fde60e95 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,7 +67,6 @@ pnpm test:ui Run package specific tests by navigating to the package and running the test command. Eg: ```bash -cd packages/core/ pnpm test --project core # addons / create / migrate / etc. ``` From 86eee66e9b7b383b5c085d3f4fe4159ee3d38ef0 Mon Sep 17 00:00:00 2001 From: Brett Date: Sat, 3 May 2025 08:24:13 +0930 Subject: [PATCH 10/18] docs: reworded project test explanation --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fde60e95..8d283ad6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,7 +65,7 @@ pnpm test:ui ``` -Run package specific tests by navigating to the package and running the test command. Eg: +Run package specific tests by specifying a project flag to the package and running the test command. Eg: ```bash pnpm test --project core # addons / create / migrate / etc. ``` From 7ca22c22221d7ff0fe07e0fa2c255b41bf7ac6fd Mon Sep 17 00:00:00 2001 From: Brett Date: Sat, 3 May 2025 08:28:45 +0930 Subject: [PATCH 11/18] docs: Integration testing explanation --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d283ad6..0fd781c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,9 @@ pnpm dev ``` ## testing + +For each add-on we have integration tests setup. These install the deps, build the app, run the dev server and then run a few small snippets against the add-on to see if the changes introduced by the add-on are working as expected. + Run all tests: ```bash #from root of project @@ -64,14 +67,11 @@ Run tests with vitest ui: pnpm test:ui ``` - Run package specific tests by specifying a project flag to the package and running the test command. Eg: ```bash pnpm test --project core # addons / create / migrate / etc. ``` -- DIRECTION REQUIRED: how to write tests. - ## styleguide ### Coding style From e44bc83626223ca5169d1ee15811867362ad1614 Mon Sep 17 00:00:00 2001 From: Brett Date: Sat, 3 May 2025 09:53:45 +0930 Subject: [PATCH 12/18] docs: updated headings for readability and grammar --- CONTRIBUTING.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0fd781c9..92052054 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,7 @@ cd cli pnpm install ``` -## build/run +## Build and run Build the project from root run 'build' script: ```bash @@ -50,7 +50,7 @@ Run build with watch mode: pnpm dev ``` -## testing +## Testing For each add-on we have integration tests setup. These install the deps, build the app, run the dev server and then run a few small snippets against the add-on to see if the changes introduced by the add-on are working as expected. @@ -60,7 +60,6 @@ Run all tests: pnpm test ``` - Run tests with vitest ui: ```bash #from root of project @@ -72,7 +71,7 @@ Run package specific tests by specifying a project flag to the package and runni pnpm test --project core # addons / create / migrate / etc. ``` -## styleguide +## Style Guide ### Coding style From 6e8b15408ecf7cf63bb13338a4e5dcbe3bce7a6d Mon Sep 17 00:00:00 2001 From: Brett Date: Sun, 4 May 2025 11:03:24 +0930 Subject: [PATCH 13/18] docs: second round fixes --- CONTRIBUTING.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92052054..69a27302 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,16 +26,15 @@ Linux users, you will have to ensure 'sudo' is not required. See [docker post in `pnpm` commands run in the project's root directory will run on all sub-projects. You can checkout the code and install the dependencies with: ```bash -git clone git@github.com:YOUR_GITHUB_USER_HERE/cli.git cd cli pnpm install ``` ## Build and run -Build the project from root run 'build' script: +To build the project and all packages. Run the 'build' script: ```bash -#from root of project +# from root of project pnpm build ``` This outputs into /packages/PACKAGE/dist/. @@ -56,13 +55,13 @@ For each add-on we have integration tests setup. These install the deps, build t Run all tests: ```bash -#from root of project +# from root of project pnpm test ``` Run tests with vitest ui: ```bash -#from root of project +# from root of project pnpm test:ui ``` @@ -88,14 +87,14 @@ pnpm lint # from root of project pnpm format ``` -- checking +- type checking ```bash # from root of project pnpm check ``` ## svelte-migrate -To run svelte-migrate from local: +To run svelte-migrate locally: ```bash # from root of project node ./packages/migrate/bin.js From 79e7aa66cacc5a4c5a3c073c3a82338258c6ad1f Mon Sep 17 00:00:00 2001 From: Brett Date: Mon, 5 May 2025 05:49:11 +0930 Subject: [PATCH 14/18] docs: added debug test starting point --- CONTRIBUTING.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69a27302..b68ab10b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,14 @@ Run package specific tests by specifying a project flag to the package and runni pnpm test --project core # addons / create / migrate / etc. ``` +To debug a failing test. A good starting point is to `cd` into the failing tests dir. `build` it.Then `preview` it. From here you will have increased information to help in the debug process. +```bash +# Each test is a standalone js app +cd .test-output/addons/[addon-test]/[test-id] +pnpm build +pnpm preview +``` + ## Style Guide ### Coding style From ca248eaf3205cbaad797729d5e7ee5c4bee04787 Mon Sep 17 00:00:00 2001 From: Brett Date: Mon, 5 May 2025 05:51:43 +0930 Subject: [PATCH 15/18] docs: added debug test starting point - edited --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b68ab10b..2dc61f9b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,7 +70,7 @@ Run package specific tests by specifying a project flag to the package and runni pnpm test --project core # addons / create / migrate / etc. ``` -To debug a failing test. A good starting point is to `cd` into the failing tests dir. `build` it.Then `preview` it. From here you will have increased information to help in the debug process. +To debug a failing test. A good starting point is to `cd` into the failing tests dir. Proceed to `build` it. Then `preview` it. From here you will have increased information to help in the debug process. ```bash # Each test is a standalone js app cd .test-output/addons/[addon-test]/[test-id] From f042bbef39b64016c6e092e5e0e0a39bdc04205d Mon Sep 17 00:00:00 2001 From: Brett Date: Mon, 5 May 2025 06:20:03 +0930 Subject: [PATCH 16/18] docs: added running individual tests --- CONTRIBUTING.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2dc61f9b..4583c539 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,17 @@ Run package specific tests by specifying a project flag to the package and runni pnpm test --project core # addons / create / migrate / etc. ``` +To run a individual test. `cd` into the package. Run the local `test` script to that package, with a path arg to the individual peice you want tested. +```bash +cd packages/[package] +pnpm test [path-to-test] +``` + +To run individual test files from root. +```bash +pnpm test [path-to-test] +``` + To debug a failing test. A good starting point is to `cd` into the failing tests dir. Proceed to `build` it. Then `preview` it. From here you will have increased information to help in the debug process. ```bash # Each test is a standalone js app From 1b260ef3f15ac1edc900719ad7c0b02303f6aedb Mon Sep 17 00:00:00 2001 From: Brett Date: Mon, 5 May 2025 06:24:41 +0930 Subject: [PATCH 17/18] docs: added running individual tests - edited --- CONTRIBUTING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4583c539..f0097c69 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,18 +70,19 @@ Run package specific tests by specifying a project flag to the package and runni pnpm test --project core # addons / create / migrate / etc. ``` -To run a individual test. `cd` into the package. Run the local `test` script to that package, with a path arg to the individual peice you want tested. +To run a individual test. `cd` into the package. Run the local `test` script to that package, with a path arg to the individual peice you want tested. Eg: ```bash cd packages/[package] pnpm test [path-to-test] ``` -To run individual test files from root. +To run individual test files from root: ```bash pnpm test [path-to-test] ``` -To debug a failing test. A good starting point is to `cd` into the failing tests dir. Proceed to `build` it. Then `preview` it. From here you will have increased information to help in the debug process. + +To debug a failing test. A good starting point is to `cd` into the failing tests dir. Proceed to `build` it. Then `preview` it. From here you will have increased information to help in the debug process. Eg: ```bash # Each test is a standalone js app cd .test-output/addons/[addon-test]/[test-id] From 091b788b37d70aae4a288236414566d97dc6460e Mon Sep 17 00:00:00 2001 From: Brett Date: Thu, 8 May 2025 05:48:39 +0930 Subject: [PATCH 18/18] update: redundant example removed. Removed specified js --- CONTRIBUTING.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0097c69..c4714b86 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,19 +72,12 @@ pnpm test --project core # addons / create / migrate / etc. To run a individual test. `cd` into the package. Run the local `test` script to that package, with a path arg to the individual peice you want tested. Eg: ```bash -cd packages/[package] pnpm test [path-to-test] ``` -To run individual test files from root: -```bash -pnpm test [path-to-test] -``` - - To debug a failing test. A good starting point is to `cd` into the failing tests dir. Proceed to `build` it. Then `preview` it. From here you will have increased information to help in the debug process. Eg: ```bash -# Each test is a standalone js app +# Each test is a standalone app cd .test-output/addons/[addon-test]/[test-id] pnpm build pnpm preview