Skip to content

Commit

Permalink
docs: Improved CONTIRUBTING.md (#6892)
Browse files Browse the repository at this point in the history
  • Loading branch information
KaminoRyo authored May 29, 2022
1 parent 869ec27 commit 5589eec
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 23 deletions.
5 changes: 5 additions & 0 deletions .changeset/ninety-gifts-swim.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"app-builder-lib": patch
---

docs: Improved CONTIRUBTING.md
87 changes: 64 additions & 23 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,33 @@
You decided to contribute to this project? Great, thanks a lot for pushing it.

This project adheres to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
This project adheres to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
By participating, you are expected to uphold this code. Please file issue to report unacceptable behavior.

This repository has a mono-repo structure consisting of multiple packages. Try to take a look at the [packages directory](https://github.com/electron-userland/electron-builder/tree/master/packages)!

## Prerequisites

> All prerequisites could be installed via script at the end of the chapter
>
* [pnpm](https://pnpm.js.org) is required because NPM is not reliable and Yarn 2 is not as good as PNPM.
* For local development, you can use [yalc](https://github.com/whitecolor/yalc) in order to apply changes made to
electron-builder for your other projects to leverage and test with.
- [pnpm](https://pnpm.js.org) is required because NPM is not reliable and Yarn 2 is not as good as PNPM.
- For local development, you can use [yalc](https://github.com/whitecolor/yalc) in order to apply changes made to
electron-builder for your other projects to leverage and test with.

```
npm install -g pnpm
npm i -g pnpm
pnpm i yalc -g
```

- (unsettled) You may need yarn. See [this issue](https://github.com/electron-userland/electron-builder/issues/6820) for details. Detailed reports are welcome.

```
npm i -g yarn
```

## To setup a local dev environment

Follow this chapter to setup an environment from scratch.

```
git clone https://github.com/electron-userland/electron-builder.git
Expand All @@ -25,38 +36,66 @@ pnpm install
popd
```

You must link `yalc`'s local "packages" to your project via the one-liner below (run from your project folder)
You must publish and link `yalc`'s local "packages" to your project via the one-liner below (run from your project folder).
Unfortunately,the `yalc publish` command cannot pass multiple packages.

```
yalc publish app-builder-lib
yalc publish builder-util
yalc publish builder-util-runtime
yalc publish dmg-builder
yalc publish electron-builder
yalc publish electron-publish
yalc publish electron-builder-squirrel-windows
yalc publish electron-forge-maker-appimage
yalc publish electron-forge-maker-nsis
yalc publish electron-forge-maker-nsis-web
yalc publish electron-forge-maker-snap
yalc publish electron-updater
yalc link app-builder-lib builder-util builder-util-runtime dmg-builder electron-builder electron-publish electron-builder-squirrel-windows electron-forge-maker-appimage electron-forge-maker-nsis electron-forge-maker-nsis-web electron-forge-maker-snap electron-updater
```

The magical script for whenever you make changes to electron-builder! Rebuilds electron-builder, and then patches
The magical script for whenever you make changes to electron-builder! Rebuilds electron-builder, and then patches
the npm modules in your project (such as `electron-quick-start`).
Ready for copy-paste into terminal presuming electron-builder repo is at root level outside your project folder,
Ready for copy-paste into terminal presuming electron-builder repo is at root level outside your project folder,
otherwise adjust path as necessary.

```
pushd ../electron-builder
pnpm compile
find packages/ -type d -maxdepth 1 -print0 | xargs -0 -L1 sh -c 'cd "$0" && yalc push'
popd
```

If you are using Windows and Visual Studio Code(Powershell), please use this.

```PowerShell
pushd ..\electron-builder
pnpm compile
Get-ChildItem packages -Directory | Foreach-Object{pushd "./packages/$_"; yalc push; popd;}
popd
```

On Windows cmd.exe:

```batch
pushd ..\electron-builder
pnpm compile
for /D %d in (packages\*) do (pushd "%d" & yalc push & popd)

This comment has been minimized.

Copy link
@piv11

piv11 Jun 7, 2022

writer

for /D %d in (packages\*) do (pushd "%d" & yalc push & popd)
popd
```

## Pull Requests

To check that your contributions match the project coding style make sure `pnpm test` passes.
To build project run: `pnpm i && pnpm compile`

> If you get strange compilation errors, try to remove all `node_modules` directories in the project (especially under `packages/*`).
>
### Git Commit Guidelines
We use [semantic-release](https://github.com/semantic-release/semantic-release), so we have very precise rules over how

We use [semantic-release](https://github.com/semantic-release/semantic-release), so we have very precise rules over how
our git [commit messages can be formatted](https://gist.github.com/develar/273e2eb938792cf5f86451fbac2bcd51).

## Documentation
Expand All @@ -71,32 +110,34 @@ Build command: `mkdocs build`.

## Debug Tests

Only IntelliJ Platform IDEs ([IntelliJ IDEA](https://confluence.jetbrains.com/display/IDEADEV/IDEA+2017.1+EAP),
Only IntelliJ Platform IDEs ([IntelliJ IDEA](https://confluence.jetbrains.com/display/IDEADEV/IDEA+2017.1+EAP),
[WebStorm](https://confluence.jetbrains.com/display/WI/WebStorm+EAP)) support debug.

If you use IntelliJ IDEA or WebStorm — [ij-rc-producer](https://github.com/develar/ij-rc-producer) is used and you
If you use IntelliJ IDEA or WebStorm — [ij-rc-producer](https://github.com/develar/ij-rc-producer) is used and you
can run tests from an editor (just click on `Run` green gutter icon).

Or you can create the Node.js run configuration manually:
* Ensure that `Before launch` contains `Compile TypeScript`.
* Set `Node interpreter` to NodeJS 8. NodeJS 8 is required to debug.
* Set `Application Parameters` to `-t "test name" relative-test-file-name` if you want to debug particular test. E.g.

- Ensure that `Before launch` contains `Compile TypeScript`.
- Set `Node interpreter` to NodeJS 8. NodeJS 8 is required to debug.
- Set `Application Parameters` to `-t "test name" relative-test-file-name` if you want to debug particular test. E.g.
```
-t "extraResources - one-package" globTest.js
```
* Set `Environment Variables`:
* Optionally, `TEST_APP_TMP_DIR` to some directory (e.g. `/tmp/electron-builder-test`) to inspect output if test
uses temporary directory (only if `--match` is used). Specified directory will be used instead of random
temporary directory and *cleared* on each run.
- Set `Environment Variables`:
- Optionally, `TEST_APP_TMP_DIR` to some directory (e.g. `/tmp/electron-builder-test`) to inspect output if test
uses temporary directory (only if `--match` is used). Specified directory will be used instead of random
temporary directory and _cleared_ on each run.

### Run Test using CLI

```sh
pnpm compile
TEST_APP_TMP_DIR=/tmp/electron-builder-test ./node_modules/.bin/jest --env jest-environment-node-debug -t 'assisted' '/oneClickInstallerTest\.\w+$'
```
where `TEST_APP_TMP_DIR` is specified to easily inspect and use test build, `assisted` is the test name
and `/oneClickInstallerTest\.\w+$` is the path to test file.

where `TEST_APP_TMP_DIR` is specified to easily inspect and use test build, `assisted` is the test name
and `/oneClickInstallerTest\.\w+$` is the path to test file.

## Issues

Expand Down

0 comments on commit 5589eec

Please sign in to comment.