cerebroapp · ogustavo-pereira · Sep 19, 2022 · Sep 16, 2022 · Sep 16, 2022
diff --git a/README.md b/README.md
@@ -1,142 +1,106 @@
 # Cerebro
 
-> Cerebro is a open-source launcher to improve your productivity and efficiency
+> Cerebro is an open-source launcher to improve your productivity and efficiency
 
 <img src="./build/icons/128x128.png" align="right"/>
 
 ## Usage
 
 You can download the latest version on  [releases](https://github.com/cerebroapp/cerebro/releases) page.
 
-After installation use default shortcut `ctrl+space` to show an app window. You can customize this shortcut clicking on icon in menu bar → preferences.
+- If there is not installer for your OS check [build instructions](#build-executable-from-source).
+- If you are a linux user see [how to install the executable](#install-executable-on-linux)
+
+After installation use the default shortcut `ctrl+space` to show the app window. You can customize this shortcut clicking on the icon in the menu bar and then selecting "Preferences...".
 
 ![Cerebro](https://cloud.githubusercontent.com/assets/594298/20180624/858a483a-a75b-11e6-94a1-ef1edc4d95c3.gif)
 
 ### Plugins
 
 ### Core plugins
 
-* Search in the web with google suggestions;
-* Search & launch application, i.e. `spotify`;
-* Navigate in file system with file previews (i.e. `~/Dropbox/passport.pdf`);
-* Calculator;
-* Smart converter. `15$`, `150 рублей в евро`, `100 eur in gbp`;
-
-## Shortcuts
-
-Cerebro provides several shortcuts to improve your productivity:
+- Search in the web with google suggestions;
+- Search & launch application, i.e. `spotify`;
+- Navigate in file system with file previews (i.e. `~/Dropbox/passport.pdf`);
+- Calculator;
+- Smart converter. `15$`, `150 рублей в евро`, `100 eur in gbp`;
 
-* `ctrl+c`: copy the result from a plugin to the clipboard, if the plugin does not provida a result, the term you introduced will be copied
-* `ctrl+1...9`: select directly a result from the list
-* `ctrl+[hjkl]`: navigate through the results using vim-like keys (Also `ctrl+o` to select the result)
+### Install plugins
 
-### Change Theme
+You can manage and install more plugins by typing `plugins <plugin-name>` in the Cerebro search bar.
 
-Use shortcut `ctrl+space` to open app window and type `Cerebro Settings`. There you will be able to change the Theme (Currently Light and Dark Themes are supported out of the box)
-
-![change-cerebro-theme](https://user-images.githubusercontent.com/24854406/56137765-5880ca00-5fb7-11e9-86d0-e740de1127c2.gif)
-
-## For developers
-
-### Install
+Discover plugins and more at [Cerebro's Awesome List](https://github.com/lubien/awesome-cerebro).
 
-First, clone the repo via git:
+> If you are interested in creating your own plugin, check the [plugins documentation](./docs/plugins-developers.md).
 
-```bash
-git clone https://github.com/cerebroapp/cerebro.git cerebro
-```
+## Shortcuts
 
-Open the project
+Cerebro provides several shortcuts to improve your productivity:
 
-```bash
-cd cerebro
-```
+- `ctrl+c`: copy the result from a plugin to the clipboard, if the plugin does not provida a result, the term you introduced will be copied
+- `ctrl+1...9`: select directly a result from the list
+- `ctrl+[hjkl]`: navigate through the results using vim-like keys (Also `ctrl+o` to select the result)
 
-And then install dependencies:
+### Change Theme
 
-```bash
-yarn
-```
+Use shortcut `ctrl+space` to open app window and type `Cerebro Settings`. There you will be able to change the Theme.
 
-### Run in development mode
+> Currently Light and Dark Themes are supported out of the box
 
-```bash
-yarn run dev
-```
+![change-cerebro-theme](https://user-images.githubusercontent.com/24854406/56137765-5880ca00-5fb7-11e9-86d0-e740de1127c2.gif)
 
-> Note: requires a node version >=16.x
+### Config file path
 
-### Install and manage custom plugins
+You can find the config file in the following path depending on your OS:
 
-Use built-in `plugins` command to search and manage custom plugins.
+*Windows*: `%APPDATA%/Cerebro/config.json`
 
-Discover plugins and more at [Cerebro's Awesome List](https://github.com/lubien/awesome-cerebro).
+*Linux*: `$XDG_CONFIG_HOME/Cerebro/config.json`  or `~/.config/Cerebro/config.json`
 
-You can install them manually using npm
+*macOS*: `~/Library/Application Support/Cerebro/config.json`
 
-open it in the terminal configuration file path, go to the plugins folder
+> ⚠️ A bad configuration file can break Cerebro. If you are not sure about what you are doing, don't edit the config file directly.
 
-```bash
-cd ./plugins
-```
+## Build executable from source
 
-Install the plugin
+If you would like to install one version of Cerebro but the executable has not been released you can follow this isntruction to build it from source:
 
- ```bash
- npm install --save name-of-plugin
- ```
+1. Clone the repository
+2. Install dependencies with `yarn`
 
-## Create plugin
+3. ```bash
+    yarn package
+   ```
 
-Check out [plugins documentation](./docs/plugins.md).
+> Note: in CI we use `yarn build` as there is an action to package and publish the executables
 
-### Build executable from source
+## Install executable on Linux
 
-If you would like to install one version but the package is not published you can use this command to build executable file from source:
+If you are a linux user you might need to grant execution permissions to the executable. To do so, open the terminal and run the following command:
 
 ```bash
-yarn package
+sudo chmod +x <path to the executable>
 ```
 
-> Note: in CI we use `yarn build` as there is an action to package and publish the executables
-
-#### Config file path
-
-*Windows*: `%APPDATA%/Cerebro/config.json`
-
-*Linux*: `$XDG_CONFIG_HOME/Cerebro/config.json`  or `~/.config/Cerebro/config.json`
-
-*macOS*: `~/Library/Application Support/Cerebro/config.json`
-
-### Resolve common issues
-
-1. `AssertionError: Current node version is not supported for development` on npm postinstall.
-After `yarn` postinstall script checks node version. If you see this error you have to check node and npm version in `package.json` `devEngines` section and install proper ones.
-
-2. `Uncaught Error: Module version mismatch. Exepcted 50, got ...`
-This error means that node modules with native extensions build with wrong node version (your local node version != node version, included to electron). To fix this issue run `cd ./app && yarn run rebuild`
-
-### Conventional Commit Format
-
-The project is using conventional commit specification to keep track of changes. This helps us with the realeases and enforces a consistent style.
-You can commit as usually or use the following commands that will help you to commit with the right style:
+Then you can install the executable by running the following command:
 
-* `yarn cz`
-* `yarn commit`
+- If you are using the AppImage executable:
 
-### Publish a release
+  ```bash
+  ./<path to the executable>
+  ```
 
-CerebroApp is using GH actions to build the app and publish it to a release. To publish a new release follow the steps below:
+- If you are using the deb executable:
 
-1. Update the version on both `package.json` and `app/package.json` files.
-2. Create a release with from GH and publish it. 🚧 The release **tag** MUST contain the `v` prefix (❌ `0.1.2` → ✅`v0.1.2`).
-3. Complete the name with a name and a description of the release.
-4. The GH action is triggered and the release is updated when executables are built.
+  ```bash
+  dpkg -i <path to the executable>
+  ```
 
-### Add dependencies
+> In some computers you might need run these commands with elevated privileges (sudo). `sudo ./<path to the executable>` or `sudo dpkg -i <path to the executable>`
 
-CerebroApp was created from an [old version of electron-react-boilerplate](https://github.com/cerebroapp/cerebro/commit/57b6e28c0f64beae8948cf17f099fa5d6236ae3c) and uses a two package.json file structure. If you are interested in developing a new feature, you should read about this structure in the [electron-react-boilerplate documentation](https://www.electron.build/tutorials/two-package-structure.html).
+## Contributing
 
+PRs are welcome! You can get a general idea of how Cerebro works by reading the [developer guide](/docs/cerebro-developers.md).
 
 ## License
 

diff --git a/docs/cerebro-developers.md b/docs/cerebro-developers.md
@@ -0,0 +1,94 @@
+# Developing Cerebro
+
+CerebroApp is an open source project and we welcome contributions from the community.
+In this document you will find information about how Cerebro works and how to contribute to the project.
+
+> ⚠️ NOTE: This document is for Cerebro developers. If you are looking for how to develop a plugin please check [plugin developers documentation](./plugins-developers).
+
+## General architecture
+
+Cerebro is based on [Electron](https://electronjs.org/) and [React](https://reactjs.org/).
+
+A basic Electron app is composed of a *main process* and a *renderer process*. The main process is responsible for the app lifecycle, the renderer process is responsible for the UI.
+
+In our case we use:
+
+- [`app/main.development.js`](/app/main.development.js) as the main process
+- [`app/main/main.js`](/app/main/main.js) as the main renderer process
+- [`app/background/background.js`](/app/background/background.js) as a secondary renderer process
+
+All this files are bundled and transpiled with [Webpack](https://webpack.js.org/) and [Babel](https://babeljs.io/).
+
+The build process is managed by [electron-builder](https://www.electron.build/).
+
+### Two renderer processes
+
+This two-renderer process architecture is used to keep the main renderer process (Cerebro) responsive and to avoid blocking the UI when executing long tasks.
+
+When we need to execute a long task we send a message to the background process, which executes the task asynchronously and sends a message back to the main renderer when the task is completed.
+
+This is the way we implement the plugins system. Their initializeAsync method is executed in the background process.
+
+## Setting up the development environment
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/en/) (>= 16)
+- [yarn](https://classic.yarnpkg.com/en/)
+
+### Install Cerebro
+
+First, clone the repo via git:
+
+```bash
+git clone https://github.com/cerebroapp/cerebro.git cerebro
+```
+
+Open the project
+
+```bash
+cd cerebro
+```
+
+And then install dependencies:
+
+```bash
+yarn
+```
+
+### Run in development mode
+
+```bash
+yarn run dev
+```
+
+> Note: requires a node version >=16.x
+
+### Resolve common issues
+
+1. `AssertionError: Current node version is not supported for development` on npm postinstall.
+After `yarn` postinstall script checks node version. If you see this error you have to check node and npm version in `package.json` `devEngines` section and install proper ones.
+
+2. `Uncaught Error: Module version mismatch. Exepcted 50, got ...`
+This error means that node modules with native extensions build with wrong node version (your local node version != node version, included to electron). To fix this issue run `yarn --force`
+
+### Conventional Commit Format
+
+The project is using conventional commit specification to keep track of changes. This helps us with the realeases and enforces a consistent style.
+You can commit as usually following this style or use the following commands that will help you to commit with the right style:
+
+- `yarn cz`
+- `yarn commit`
+
+### Publish a release
+
+CerebroApp is using GH actions to build the app and publish it to a release. To publish a new release follow the steps below:
+
+1. Update the version on both `package.json` and `app/package.json` files.
+2. Create a release with from GH and publish it. 🚧 The release **tag** MUST contain the `v` prefix (❌ `0.1.2` → ✅`v0.1.2`).
+3. Complete the name with a name and a description of the release.
+4. The GH action is triggered and the release is updated when executables are built.
+
+### Add dependencies
+
+CerebroApp was created from an [old version of electron-react-boilerplate](https://github.com/cerebroapp/cerebro/commit/57b6e28c0f64beae8948cf17f099fa5d6236ae3c) and uses a two package.json file structure. If you are interested in developing a new feature, you should read about this structure in the [electron-react-boilerplate documentation](https://www.electron.build/tutorials/two-package-structure.html).
diff --git a/docs/plugins-developers.md b/docs/plugins-developers.md
@@ -0,0 +1,41 @@
+# Plugins
+
+> ⚠️ NOTE: This document is for Plugin developers. If you are looking for how to contribute to Cerebro core please check [Cerebro documentation](./cerebro-developers.md).
+
+A Cerebro plugin is just a javascript module. All you need is to write a function, that takes one object and call a function from arguments with your results.
+
+You can create your plugin using [create-cerebro-plugin](https://github.com/cerebroapp/create-cerebro-plugin) so you can focus on code of your plugin, not on tools and configuration around it.
+
+Links:
+
+* [Plugin structure](./plugins/plugin-structure.md);
+* [Cerebro tools](https://github.com/cerebroapp/cerebro-tools);
+* [Cerebro UI](https://github.com/cerebroapp/cerebro-ui);
+* [Styles](./plugins/styles.md) for you plugin previews;
+* [Share your plugin](./plugins/share.md);
+* [Examples](./plugins/examples.md);
+
+## Prerequisites
+
+* [Node.js](https://nodejs.org/en/) (>= 16)
+* [yarn](https://classic.yarnpkg.com/en/)
+
+## Install and manage custom plugins
+
+Sometimes you need to manually install a plugin (maybe you have published it to npm but you dind't added the keywords to the package.json so it is not available in Cerebro).
+If you want to test this plugin, you can install it manually:
+
+1. Open a terminal in the [configuration directory](/docs/cerebro-developers.md#config-file-path) of Cerebro
+2. Go to the plugins directory
+
+    ```bash
+    cd ./plugins
+    ```
+
+3. Install the plugin
+
+    ```bash
+    npm install --save name-of-plugin
+    ```
+
+4. Restart Cerebro
diff --git a/docs/plugins.md b/docs/plugins.md