diff options
author | davidajetter-tw <105304388+davidajetter-tw@users.noreply.github.com> | 2022-06-14 18:26:11 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-06-14 22:26:11 +0000 |
commit | 243004ddfabda2ae908599fac364dae0fdcdf04a (patch) | |
tree | 90e700414daf015bdc188002340f11c44465e16c /CONTRIBUTING.md | |
parent | Add startpage.com as option search-engine and make it the default for new use... (diff) | |
download | ferdium-app-243004ddfabda2ae908599fac364dae0fdcdf04a.tar.gz ferdium-app-243004ddfabda2ae908599fac364dae0fdcdf04a.tar.zst ferdium-app-243004ddfabda2ae908599fac364dae0fdcdf04a.zip |
Update CONTRIBUTING.md for new contributors' dev machine setup [skip ci]
Co-authored-by: Vijay A <vraravam@users.noreply.github.com>
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r-- | CONTRIBUTING.md | 85 |
1 files changed, 20 insertions, 65 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01f638e99..600ae7e73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md | |||
@@ -19,17 +19,13 @@ | |||
19 | - [On Fedora](#on-fedora) | 19 | - [On Fedora](#on-fedora) |
20 | - [On Windows](#on-windows) | 20 | - [On Windows](#on-windows) |
21 | - [Clone repository with submodule](#clone-repository-with-submodule) | 21 | - [Clone repository with submodule](#clone-repository-with-submodule) |
22 | - [Local caching of dependencies](#local-caching-of-dependencies) | 22 | - [Run the script](#run-the-script) |
23 | - [Install dependencies](#install-dependencies) | 23 | - [Using Docker to build a linux-targetted packaged app (not supported as a 1st-class citizen)](#using-docker-to-build-a-linux-targetted-packaged-app-not-supported-as-a-1st-class-citizen) |
24 | - [Fix native modules to match current electron node version](#fix-native-modules-to-match-current-electron-node-version) | ||
25 | - [Package recipe repository](#package-recipe-repository) | ||
26 | - [Using Docker to build a linux-targetted packaged app](#using-docker-to-build-a-linux-targetted-packaged-app) | ||
27 | - [Code Signing on a mac](#code-signing-on-a-mac) | ||
28 | - [Start development app](#start-development-app) | 24 | - [Start development app](#start-development-app) |
29 | - [Styleguide](#styleguide) | 25 | - [Styleguide](#styleguide) |
30 | - [Git Commit Messages format](#git-commit-messages-format) | 26 | - [Git Commit Messages format](#git-commit-messages-format) |
31 | - [Javascript Coding style-checker](#javascript-coding-style-checker) | 27 | - [Javascript Coding style-checker](#javascript-coding-style-checker) |
32 | - [Packaging](#packaging) | 28 | - [Code Signing on a mac (not necessary in the normal circumstances)](#code-signing-on-a-mac-not-necessary-in-the-normal-circumstances) |
33 | - [Release](#release) | 29 | - [Release](#release) |
34 | - [Nightly releases](#nightly-releases) | 30 | - [Nightly releases](#nightly-releases) |
35 | - [Updating the code after a hiatus](#updating-the-code-after-a-hiatus) | 31 | - [Updating the code after a hiatus](#updating-the-code-after-a-hiatus) |
@@ -61,7 +57,7 @@ _Note:_ This list can likely get outdated. If so, please refer to the specific v | |||
61 | 57 | ||
62 | Please make sure you are conforming to the `engines` requirements used by the developers/contributors as specified in the [`package.json`](./package.json#engines) and [`recipes/package.json`](./recipes/package.json#engine) files. | 58 | Please make sure you are conforming to the `engines` requirements used by the developers/contributors as specified in the [`package.json`](./package.json#engines) and [`recipes/package.json`](./recipes/package.json#engine) files. |
63 | 59 | ||
64 | Currently, these are the combinations of system dependencies that work for MacOS/Linux/Windows: | 60 | Currently, these are the combinations of system dependencies that work for MacOS/Linux/Windows. Versions are pinned down to the patch number so ensure you have the exact matching versions installed and in use. |
65 | 61 | ||
66 | ```bash | 62 | ```bash |
67 | # Note: 'jq' is not a required system dependency; its only here to show the combined output of versions needed | 63 | # Note: 'jq' is not a required system dependency; its only here to show the combined output of versions needed |
@@ -100,53 +96,30 @@ Please make sure you have the following installed: | |||
100 | ### Clone repository with submodule | 96 | ### Clone repository with submodule |
101 | 97 | ||
102 | ```bash | 98 | ```bash |
103 | git clone https://github.com/ferdium/ferdium.git | 99 | git clone https://github.com/ferdium/ferdium-app.git |
104 | cd ferdium | 100 | cd ferdium-app |
105 | git submodule update --init --recursive --remote --rebase --force | 101 | git submodule update --init --recursive --remote --rebase --force |
106 | ``` | 102 | ``` |
107 | 103 | ||
108 | It is important you execute the last command to get the required submodule (ferdium-recipes). | 104 | It is important you execute the last command to get the required submodule (`ferdium-recipes`). |
109 | 105 | ||
110 | ### Local caching of dependencies | 106 | ### Run the script |
111 | 107 | ||
112 | Set these env vars into your profile (or if you use [direnv](https://direnv.net/), you can manage them via the respective `.envrc` file) | 108 | Run the following script to install all dependencies, and build Ferdium. |
113 | 109 | ||
114 | ```bash | 110 | ```bash |
115 | # On bash or equivalent | 111 | # On Unix |
116 | export ELECTRON_CACHE=$HOME/.cache/electron | 112 | ./scripts/build-unix.sh |
117 | export ELECTRON_BUILDER_CACHE=$HOME/.cache/electron-builder | ||
118 | |||
119 | # On Powershell | ||
120 | $env:CI = $true | ||
121 | $env:ELECTRON_CACHE = $HOME + '\.cache\electron' | ||
122 | $env:ELECTRON_BUILDER_CACHE = $HOME + '\.cache\electron-builder' | ||
123 | ``` | ||
124 | |||
125 | ### Install dependencies | ||
126 | |||
127 | Run the following command to install all dependencies, and link sibling modules with Ferdium. | ||
128 | |||
129 | ```bash | ||
130 | npm i | ||
131 | ``` | ||
132 | |||
133 | If you encounter the `gyp: No Xcode or CLT version` error on macOS at this step, please have a look [here](https://medium.com/flawless-app-stories/gyp-no-xcode-or-clt-version-detected-macos-catalina-anansewaa-38b536389e8d). | ||
134 | |||
135 | ### Fix native modules to match current electron node version | ||
136 | 113 | ||
137 | ```bash | 114 | # On Windows Powershell |
138 | npm run build | 115 | .\scripts\build-windows.ps1 |
139 | ``` | 116 | ``` |
140 | 117 | ||
141 | ### Package recipe repository | 118 | Assets will be available in the `out` folder. |
142 | |||
143 | Ferdium requires its recipes to be packaged before it can use it. When running Ferdium as a development instance, you'll need to package the local recipes before you can create any services inside Ferdium. | ||
144 | 119 | ||
145 | ```bash | 120 | If you encounter the `gyp: No Xcode or CLT version` error on macOS at this step, please have a look [here](https://medium.com/flawless-app-stories/gyp-no-xcode-or-clt-version-detected-macos-catalina-anansewaa-38b536389e8d). |
146 | cd recipes && pnpm i && pnpm package | ||
147 | ``` | ||
148 | 121 | ||
149 | ### Using Docker to build a linux-targetted packaged app | 122 | ### Using Docker to build a linux-targetted packaged app (not supported as a 1st-class citizen) |
150 | 123 | ||
151 | ```bash | 124 | ```bash |
152 | docker build -t ferdium-package-`uname -m` . | 125 | docker build -t ferdium-package-`uname -m` . |
@@ -170,20 +143,6 @@ mv /ferdium/ferdium /ferdium-out/Ferdium-$GIT_SHA | |||
170 | mv /ferdium/latest-linux.yml /ferdium-out/latest-linux-$GIT_SHA.yml | 143 | mv /ferdium/latest-linux.yml /ferdium-out/latest-linux-$GIT_SHA.yml |
171 | ``` | 144 | ``` |
172 | 145 | ||
173 | ### Code Signing on a mac | ||
174 | |||
175 | If you are building the packaged app (on a mac) for local testing, you can set this environment variable to bypass the code signing step during the packaging process (`npm run build`): | ||
176 | |||
177 | ```bash | ||
178 | export CSC_IDENTITY_AUTO_DISCOVERY=false | ||
179 | ``` | ||
180 | |||
181 | Or else, if you want to self-sign on a mac with non-registered certificate (not for distribution of the resulting package), you can follow [this thread](https://github.com/electron/electron/issues/7476#issuecomment-356084754) and run this command: | ||
182 | |||
183 | ```bash | ||
184 | codesign --deep --force --verbose --sign - node_modules/electron/dist/Electron.app | ||
185 | ``` | ||
186 | |||
187 | ### Start development app | 146 | ### Start development app |
188 | 147 | ||
189 | Run this command on the terminal: | 148 | Run this command on the terminal: |
@@ -210,18 +169,14 @@ Please use the `src/preload-safe-debug` module instead until the bug gets fixed. | |||
210 | 169 | ||
211 | - Please use `prettier` and the defined rules to maintain a consistent style | 170 | - Please use `prettier` and the defined rules to maintain a consistent style |
212 | 171 | ||
213 | ## Packaging | 172 | ### Code Signing on a mac (not necessary in the normal circumstances) |
214 | 173 | ||
215 | ```bash | 174 | If you want to self-sign on a mac with non-registered certificate (not for distribution of the resulting package), you can follow [this thread](https://github.com/electron/electron/issues/7476#issuecomment-356084754) and run this command: |
216 | # On Unix | ||
217 | ./scripts/build-unix.sh | ||
218 | 175 | ||
219 | # On Windows | 176 | ```bash |
220 | .\scripts\build-windows.ps1 | 177 | codesign --deep --force --verbose --sign - node_modules/electron/dist/Electron.app |
221 | ``` | 178 | ``` |
222 | 179 | ||
223 | Assets will be available in the `out` folder. | ||
224 | |||
225 | ## Release | 180 | ## Release |
226 | 181 | ||
227 | ```bash | 182 | ```bash |