diff --git a/docs/linking.md b/docs/linking.md index b9c62edf..1016fffb 100644 --- a/docs/linking.md +++ b/docs/linking.md @@ -1,9 +1,13 @@ ## Quickstart guide + run + ```bash ./scripts/setup-linking.sh ``` + Read the script output: + ``` Setup complete. Update: .links.cjs to your liking @@ -14,7 +18,6 @@ Run: 'git config --local core.hooksPath ""' to allow committing with linking (no Run: 'rm links.cjs' & 'git config --local core.hooksPath ""' to fully revert what this script did ``` - # Developing with linked packages If you want to make changes to a package that Element Call depends on and see those changes applied in real time, you can create a link to a local copy of the package. `pnpm` has a command for this (`pnpm link`), but it's not recommended to use it as it ends up modifying package.json with details specific to your development environment. @@ -54,7 +57,9 @@ To activate the hooks configure git with (when using the setup script (`./script ```bash git config --local core.hooksPath .githooks ``` + This will add the hook path for this repository only to .gihooks. which is a tracked (by git) folder containing the pre-commit hook. ## Background + Information, why this approach is used can be found in the [linking concept reasoning](./linking_concept_reasoning.md) document. diff --git a/docs/linking_concept_reasoning.md b/docs/linking_concept_reasoning.md index 37221344..7c135a96 100644 --- a/docs/linking_concept_reasoning.md +++ b/docs/linking_concept_reasoning.md @@ -1,27 +1,30 @@ - ### Why do we not enable .pnpmfile.cjs by default + Background: The presence of the `.pnpmfile.cjs` adds a field to the `pnpm-lock.yaml` called: `pnpmfileChecksum`. This field is a checksum of the content of the `.pnpmfile.cjs` file. `pnpm install --frozen-lockfile` **fails** if there is a `.pnpmfile.cjs` but no `pnpmfileChecksum` or vice versa (or on mismatch). _TLDR: running with `--ignore-pnpmfile` will fail if `pnpmfileChecksum` is present._ #### `pnpmfileChecksum` + renovate bot + When the renovate bot creates a PR it runs `pnpm install --ignore-pnpmfile`. This means that the `pnpmfileChecksum` in the lockfile will be **empty**. This breaks builds that **don't** ignore the `.pnpmfile.cjs`-file. (CI that runs on the renovate PR) From here we have two possible paths: - - ignore `.pnpmfile.cjs` in all CI builds CI will also fail if we accidently add it locally. - - fixup the `pnpm-lock.yaml` in the renovate PR to contain the correct `pnpmfileChecksum`. - - Ignoring in all CI builds means that CI will always fail if we enable the linking system. - This is annoying but can be worked around with the git hook we provide that at least lets us know that we are - commiting with enabled linking. - Only if we remember setting it back/disbale linking (or let ourselves remember by the git hook) the CI will work. - #### Summary - - We will always run into conflicts with the `pnpmfileChecksum` because in renovate prs it will be empty (`--ignore-pnpmfile`) - - To keep it simple we set `--ignore-pnpmfile` in all of ours CI to see issues immediately. - - The only solution is to never have a `.pnpmfile.cjs` in the repository when pushing. - - This way there will never be a commit with `pnpmfileChecksum` in the lockfile. - - renovate (which uses `--ignore-pnpmfile` which we cannot disable) and other CI will work - - We are able to use the linking system locally if we `cp` this file from the scripts folder into `./` on demand. - - `pnpm links:on` and `pnpm links:off` + `./scripts/setup-linking.sh` will help us with this. +- ignore `.pnpmfile.cjs` in all CI builds CI will also fail if we accidently add it locally. +- fixup the `pnpm-lock.yaml` in the renovate PR to contain the correct `pnpmfileChecksum`. + +Ignoring in all CI builds means that CI will always fail if we enable the linking system. +This is annoying but can be worked around with the git hook we provide that at least lets us know that we are +commiting with enabled linking. +Only if we remember setting it back/disbale linking (or let ourselves remember by the git hook) the CI will work. + +#### Summary + +- We will always run into conflicts with the `pnpmfileChecksum` because in renovate prs it will be empty (`--ignore-pnpmfile`) +- To keep it simple we set `--ignore-pnpmfile` in all of ours CI to see issues immediately. +- The only solution is to never have a `.pnpmfile.cjs` in the repository when pushing. + - This way there will never be a commit with `pnpmfileChecksum` in the lockfile. + - renovate (which uses `--ignore-pnpmfile` which we cannot disable) and other CI will work +- We are able to use the linking system locally if we `cp` this file from the scripts folder into `./` on demand. +- `pnpm links:on` and `pnpm links:off` + `./scripts/setup-linking.sh` will help us with this.