diff options
author | Vijay Raghavan Aravamudhan <vraravam@users.noreply.github.com> | 2021-05-12 21:35:59 +0530 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-05-12 21:35:59 +0530 |
commit | e01f9bd833e0e7c36b5a9304a3aa012a8fce9331 (patch) | |
tree | 47f6e43e712a6deefe946b15d6cf8c77e2da08a4 /CONTRIBUTING.md | |
parent | Remove duplicated lines (probably introduced in a bad conflict-resolution step). (diff) | |
download | ferdium-app-e01f9bd833e0e7c36b5a9304a3aa012a8fce9331.tar.gz ferdium-app-e01f9bd833e0e7c36b5a9304a3aa012a8fce9331.tar.zst ferdium-app-e01f9bd833e0e7c36b5a9304a3aa012a8fce9331.zip |
Updated the documentation (#1394)
Restructured the documentation. Added an important section for self-help: 'Troubleshooting recipes'. [skip ci]
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r-- | CONTRIBUTING.md | 189 |
1 files changed, 175 insertions, 14 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e1b557edd..82894cf5a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md | |||
@@ -2,13 +2,34 @@ | |||
2 | 2 | ||
3 | :tada: First off, thanks for taking the time and your effort to make Ferdi better! :tada: | 3 | :tada: First off, thanks for taking the time and your effort to make Ferdi better! :tada: |
4 | 4 | ||
5 | #### Table of contents | 5 | ## Table of contents |
6 | |||
6 | <!-- TOC depthFrom:2 depthTo:2 withLinks:1 updateOnSave:1 orderedList:0 --> | 7 | <!-- TOC depthFrom:2 depthTo:2 withLinks:1 updateOnSave:1 orderedList:0 --> |
7 | 8 | ||
8 | - [Code of Conduct](#code-of-conduct) | 9 | - [Contributing to Ferdi 5](#contributing-to-ferdi-5) |
9 | - [What should I know before I get started?](#what-should-i-know-before-i-get-started) | 10 | - [Table of contents](#table-of-contents) |
10 | - [How Can I Contribute?](#how-can-i-contribute) | 11 | - [Code of Conduct](#code-of-conduct) |
11 | - [Styleguide](#styleguide) | 12 | - [What should I know before I get started?](#what-should-i-know-before-i-get-started) |
13 | - [How Can I Contribute?](#how-can-i-contribute) | ||
14 | - [Setting up your Development machine](#setting-up-your-development-machine) | ||
15 | - [Install System-level dependencies](#install-system-level-dependencies) | ||
16 | - [Node.js, npm, node-gyp](#nodejs-npm-node-gyp) | ||
17 | - [Git](#git) | ||
18 | - [Debian/Ubuntu](#debianubuntu) | ||
19 | - [Fedora](#fedora) | ||
20 | - [Windows](#windows) | ||
21 | - [Clone repository with submodule](#clone-repository-with-submodule) | ||
22 | - [Local caching of dependencies](#local-caching-of-dependencies) | ||
23 | - [Install dependencies](#install-dependencies) | ||
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 an rpm package](#using-docker-to-build-an-rpm-package) | ||
27 | - [Start development app](#start-development-app) | ||
28 | - [Styleguide](#styleguide) | ||
29 | - [Git Commit Messages format](#git-commit-messages-format) | ||
30 | - [Javascript Coding style-checker](#javascript-coding-style-checker) | ||
31 | - [Packaging](#packaging) | ||
32 | - [Release](#release) | ||
12 | 33 | ||
13 | <!-- /TOC --> | 34 | <!-- /TOC --> |
14 | 35 | ||
@@ -17,18 +38,158 @@ | |||
17 | This project and everyone participating in it is governed by the [Ferdi Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [stefan@adlk.io](mailto:stefan@adlk.io). | 38 | This project and everyone participating in it is governed by the [Ferdi Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [stefan@adlk.io](mailto:stefan@adlk.io). |
18 | 39 | ||
19 | ## What should I know before I get started? | 40 | ## What should I know before I get started? |
41 | |||
20 | For the moment, Ferdi's development is a bit slow but all contributions are highly appreciated. [Check this issue for discussion](https://github.com/getferdi/ferdi/issues/956). | 42 | For the moment, Ferdi's development is a bit slow but all contributions are highly appreciated. [Check this issue for discussion](https://github.com/getferdi/ferdi/issues/956). |
21 | 43 | ||
22 | ## How Can I Contribute? | 44 | ## How Can I Contribute? |
45 | |||
23 | As a basic rule, before filing issues, feature requests or anything else. Take a look at the issues and check if this has not already been reported by another user. If so, engage in the already existing discussion. | 46 | As a basic rule, before filing issues, feature requests or anything else. Take a look at the issues and check if this has not already been reported by another user. If so, engage in the already existing discussion. |
24 | 47 | ||
25 | ## Styleguide | 48 | ## Setting up your Development machine |
26 | ### Git Commit Messages | 49 | |
27 | * Use the present tense ("Add feature" not "Added feature") | 50 | ### Install System-level dependencies |
28 | * Use the imperative mood ("Move cursor to..." not "Moves cursor to...") | 51 | |
29 | * Limit the first line to 72 characters or less | 52 | #### Node.js, npm, node-gyp |
30 | * Reference issues and pull requests liberally after the first line | 53 | |
31 | * When only changing documentation, include `[ci skip]` in the commit description | 54 | Please make sure you are running the exact node version used by the developers/contributors as specified in the [nvmrc file](./.nvmrc). |
55 | |||
56 | Currently, these are the combinations of system dependencies that work on an intel-based machines for MacOS/Linux/Windows (building on an ARM-based machine is still a work-in-progress due to node-sass native dependencies) | ||
57 | |||
58 | ```bash | ||
59 | node -v | ||
60 | v14.16.1 | ||
61 | npm -v | ||
62 | 6.14.12 | ||
63 | node-gyp -v | ||
64 | v8.0.0 | ||
65 | ``` | ||
66 | |||
67 | #### Git | ||
68 | |||
69 | The version [2.23.0](https://github.com/git-for-windows/git/releases/tag/v2.23.0.windows.1) for Git is working fine for development. You can then use the console from Git to do the development procedure. | ||
70 | |||
71 | #### Debian/Ubuntu | ||
72 | |||
73 | ```bash | ||
74 | apt install libx11-dev libxext-dev libxss-dev libxkbfile-dev rpm | ||
75 | ``` | ||
76 | |||
77 | #### Fedora | ||
78 | |||
79 | ```bash | ||
80 | dnf install libX11-devel libXext-devel libXScrnSaver-devel libxkbfile-devel rpm | ||
81 | ``` | ||
82 | |||
83 | #### Windows | ||
84 | |||
85 | Please make sure you run this command as an administrator: | ||
86 | |||
87 | ```bash | ||
88 | npm install --global windows-build-tools --vs2015 | ||
89 | ``` | ||
90 | |||
91 | ### Clone repository with submodule | ||
92 | |||
93 | ```bash | ||
94 | git clone https://github.com/getferdi/ferdi.git | ||
95 | cd ferdi | ||
96 | git submodule update --init --recursive | ||
97 | ``` | ||
98 | |||
99 | It is important you execute the last command to get the required submodules (recipes, server). | ||
100 | |||
101 | ### Local caching of dependencies | ||
102 | |||
103 | Set these env vars into your profile (or if you use [direnv](https://direnv.net/), you can manage them via the respective `.envrc` file) | ||
104 | ```bash | ||
105 | export ELECTRON_CACHE=$HOME/.cache/electron | ||
106 | export ELECTRON_BUILDER_CACHE=$HOME/.cache/electron-builder | ||
107 | ``` | ||
108 | |||
109 | ### Install dependencies | ||
110 | |||
111 | Run the following command to install all dependencies, and link sibling modules with Ferdi. | ||
112 | |||
113 | ```bash | ||
114 | npx lerna bootstrap | ||
115 | ``` | ||
116 | |||
117 | If you previously ran `npm install`, it sometimes is necessary to delete your `node_modules` folder before running `npx lerna bootstrap`. 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). | ||
118 | |||
119 | ### Fix native modules to match current electron node version | ||
120 | |||
121 | ```bash | ||
122 | npm run rebuild | ||
123 | ``` | ||
124 | |||
125 | ### Package recipe repository | ||
126 | |||
127 | Ferdi requires its recipes to be packaged before it can use it. When running Ferdi as a development instance, you'll need to package the local recipes before you can create any services inside Ferdi. | ||
128 | |||
129 | ```bash | ||
130 | cd recipes | ||
131 | npm install && npm run package | ||
132 | ``` | ||
133 | |||
134 | ### Using Docker to build an rpm package | ||
135 | |||
136 | ```bash | ||
137 | docker build -t ferdi-package . | ||
138 | docker run -v tmp-out:/ferdi-out -it ferdi-package sh | ||
139 | ``` | ||
140 | |||
141 | The above will place all the built artifacts into the `/ferdi` folder within the image. If you want to copy them outside of the image, simply mount a volume into a different location, and copy all files from `/ferdi` into the mounted folder (`/ferdi-out` in the 2nd example command above). | ||
142 | |||
143 | ### Start development app | ||
144 | |||
145 | Run these two commands **simultaneously** in different terminals: | ||
146 | |||
147 | ```bash | ||
148 | npm run dev | ||
149 | DEBUG=Ferdi:* npm run start | ||
150 | ``` | ||
151 | |||
152 | Optionally, you can run both commands in one terminal with [misty](https://github.com/adlk/misty) (see [misty.yml](https://github.com/getferdi/ferdi/blob/develop/misty.yml)): | ||
153 | |||
154 | ```bash | ||
155 | DEBUG=Ferdi:* npx misty | ||
156 | ``` | ||
157 | |||
158 | Note: please prefer [`debug()`](https://github.com/visionmedia/debug) over `console.log()`. | ||
159 | |||
160 | ### Styleguide | ||
161 | |||
162 | #### Git Commit Messages format | ||
163 | |||
164 | - Use the present tense ("Add feature" not "Added feature") | ||
165 | - Use the imperative mood ("Move cursor to..." not "Moves cursor to...") | ||
166 | - Limit the first line to 72 characters or less | ||
167 | - Reference issues and pull requests liberally after the first line | ||
168 | - When only changing documentation, include `[ci skip]` in the commit description | ||
169 | |||
170 | #### Javascript Coding style-checker | ||
171 | |||
172 | - Please use `es-lint` and the defined rules to maintain a consistent style | ||
173 | |||
174 | ## Packaging | ||
175 | |||
176 | ```bash | ||
177 | npm run build | ||
178 | ``` | ||
179 | |||
180 | Assets will be available in the `out` folder. | ||
181 | |||
182 | ## Release | ||
183 | |||
184 | Create a new [draft release](https://github.com/getferdi/ferdi/releases/new) that targets the `release` branch, then: | ||
185 | |||
186 | ```bash | ||
187 | git checkout develop && git pull -r | ||
188 | git checkout release | ||
189 | git submodule update --remote --force | ||
190 | git commit -am "Update submodules" | ||
191 | git merge --no-ff develop | ||
192 | git push | ||
193 | ``` | ||
32 | 194 | ||
33 | ### Javascript | 195 | Once the draft release assets are uploaded (13 assets), publish the release (you will need elevated permissions in GitHub for doing this). The last commit of the `release` branch will be tagged. You can then merge `release` into `master` and back into `develop` if needed |
34 | * Please use `es-lint` and the defined rules to maintain a consistent style | ||