aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/integration.md36
-rw-r--r--docs/updating.md36
2 files changed, 19 insertions, 53 deletions
diff --git a/docs/integration.md b/docs/integration.md
index d186704..4de4953 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -6,7 +6,7 @@ A Ferdi recipe is basically nothing else than a node module and is currently ini
6 6
7> ℹ️ New to Ferdi recipes and Electron? Then we recommend you read Jake Lee's ["Super simple guide to adding a new Ferdi service recipe"](https://blog.jakelee.co.uk/super-simple-guide-to-adding-a-new-ferdi-service-recipe/) which gives you an easy step-by-step guide on how to create and publish your recipe! 7> ℹ️ New to Ferdi recipes and Electron? Then we recommend you read Jake Lee's ["Super simple guide to adding a new Ferdi service recipe"](https://blog.jakelee.co.uk/super-simple-guide-to-adding-a-new-ferdi-service-recipe/) which gives you an easy step-by-step guide on how to create and publish your recipe!
8 8
9> ℹ️ If you have any problems packaging your recipes, if you are inexperienced with the tools used or have any other problems, we are here to help! Just open a new issue at https://github.com/getferdi/recipes/issues/new and we can help you develop, test and publish your recipe and can package the recipe for you if you don't feel like you are able to. 9> ℹ️ If you have any problems packaging your recipes, if you are inexperienced with the tools used or have any other problems, we are here to help! Just open a new issue at https://github.com/getferdi/recipes/issues/new and we can help you develop, test and publish your recipe
10 10
11> If you want to update an existing recipe, please refer to [updating.md](https://github.com/getferdi/recipes/blob/master/docs/updating.md) instead 11> If you want to update an existing recipe, please refer to [updating.md](https://github.com/getferdi/recipes/blob/master/docs/updating.md) instead
12 12
@@ -25,25 +25,26 @@ A Ferdi recipe is basically nothing else than a node module and is currently ini
25 - [Publishing](#publishing) 25 - [Publishing](#publishing)
26 26
27## Preparing 27## Preparing
28Before you can begin, you should have [NodeJS](http://nodejs.org/) installed and should be familiar with using npm, specifically "npm install" and "npm run". 28You should have basic knowledge of JavaScript - don't worry, you'll really only need some basic commands as we've already prepared the complicated stuff for you.
29 29
30You should also have basic knowledge of JavaScript - don't worry, you'll really only need some basic commands as we've already prepared the complicated stuff for you. 30We have also created a nice script that already does 50% of the work for you - yay 🎉. If you want to use this script, please make sure you have NodeJS installed on your system.
31 31
32## Create a recipe 32## Create a recipe
331. Clone this repository. You can do this by running `git clone https://github.com/getferdi/recipes.git` in your terminal or by downloading the repository from <https://github.com/getferdi/recipes/archive/master.zip>. 331. Fork this repository on GitHub. You can do this by clicking the "Fork" button in the top right corner
342. Install its dependencies via the terminal: 342. Clone your forked repository. Normally, you can do this by running `git clone https://github.com/<Your GitHub Username>/recipes.git` in your terminal. You may also use a Git GUI or the GitHub Website for this.
352. (Optional, if you want to use our creation script) Install its dependencies via the terminal:
35```Bash 36```Bash
36cd scripts/
37npm install 37npm install
38``` 38```
393. You can now run our automatic recipe wizard that creates and opens the new recipe for you: 393. You can now run our automatic recipe wizard that creates and opens the new recipe for you:
40```Bash 40```Bash
41# Make sure you are still in the scripts/ folder 41# Make sure you are still in the repository's folder
42npm run create "Service Name" 42npm run create "Service Name"
43``` 43```
44Replace `Service Name` with the name of your service, e.g. `npm run create "Google Hangouts"`. 44Replace `Service Name` with the name of your service, e.g. `npm run create "Google Hangouts"`.
45This command will automatically create the development recipe in the correct folder, prepares it for your service and opens the new recipe in your file explorer or Finder. 45This command will automatically create the development recipe in the correct folder, prepares it for your service and opens the new recipe in your file explorer or Finder.
464. Reload Ferdi (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe 464. Reload Ferdi (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe
475. You can now develop your recipe as described below. Please continue down below with "[Publishing](#Publishing)" after you are done creating your recipe.
47 48
48## Recipe structure 49## Recipe structure
49Every recipe needs a specific file structure in order to work as a Ferdi recipe 50Every recipe needs a specific file structure in order to work as a Ferdi recipe
@@ -179,21 +180,6 @@ In order to debug your service integration, open Ferdi and use the shortcut `Cmd
179## Publishing 180## Publishing
180Ferdi uses its recipe repository at <https://github.com/getferdi/recipes> to publish recipes to all clients. 181Ferdi uses its recipe repository at <https://github.com/getferdi/recipes> to publish recipes to all clients.
181 182
182> Our scripts are designed to work best on Linux and macOS systems. If you want to use these scripts on Windows, you may need to use [WSL](https://docs.microsoft.com/en-US/windows/wsl/install-win10) in order for the scripts to function correctly. If you have problems with packaging, please open a new issue at https://github.com/getferdi/recipes/issues/new and we can package your recipe for you. 183Publishing your recipes to Ferdi is super easy! When you used our recipe creation script, we have created a folder for your recipe inside Ferdi's internal folders (the one that got automatically opened after you ran our script).
183 184
184To add your own recipe to the repository: 185Simply copy that whole folder into the repositories "recipes" folder. You'll now need to push your changes to Git and create a Pull Request from your fork repository to our repository using the GitHub website. \ No newline at end of file
185- If you already uploaded the recipe to GitHub:
186 1. Fork https://github.com/getferdi/recipes and clone it to your computer
187 2. Open a terminal in the `scripts/` folder of that repository
188 3. Run `npm install` to install all dependencies
189 4. Run `npm run github [GitHub URL]`, e.g. `npm run github https://github.com/vantezzen/franz-recipe-standardnotes`, to add your new recipe
190 5. Create a PR to <https://github.com/getferdi/recipes> with your new changes
191
192- If you don't have it uploaded it GitHub:
193 ℹ️ We recommend uploading your recipes to GitHub before adding them to provide a platform for users to report issues.
194 1. Fork https://github.com/getferdi/recipes and clone it to your computer
195 2. Copy your recipe files into `scripts/recipe_src`
196 3. Open a terminal at `scripts/`
197 4. Run `npm install` to install all dependencies
198 5. Run `npm run package` to package your new recipe
199 6. Create a PR to <https://github.com/getferdi/recipes> with your new changes
diff --git a/docs/updating.md b/docs/updating.md
index ac2e126..000b362 100644
--- a/docs/updating.md
+++ b/docs/updating.md
@@ -2,16 +2,6 @@
2 2
3If you want to improve or update an existing recipe, please follow this guide. 3If you want to improve or update an existing recipe, please follow this guide.
4 4
5Please **do not** simply change files inside `uncompressed` - Ferdi only uses the packaged archives, the uncompressed files are only to improve accessibility of the repository.
6
7## 0. Find the recipe ID of the recipe you want to update
8
9Before you can start updating the recipe, you'll need to know its internal ID. The ID is a string of lowercase letters and hyphens that Ferdi uses to store and manage them.
10
11To find the recipe ID, you can search <https://github.com/getferdi/recipes/blob/master/all.json> for the recipe you want to edit.
12
13In the rest of this guide, always replace "&lt;recipe id>" with the ID of the recipe you want to edit.
14
15## 1. Implement your updates 5## 1. Implement your updates
16 6
17We highly suggest that you implement and test your updates to the recipe inside Ferdi before implementing them into the recipe repository. This will save you time on debugging and repackaging the recipe later. 7We highly suggest that you implement and test your updates to the recipe inside Ferdi before implementing them into the recipe repository. This will save you time on debugging and repackaging the recipe later.
@@ -21,32 +11,22 @@ You can find the recipe source Ferdi uses at:
21 * Windows: `%appdata%/Ferdi/recipes/<recipe id>/` 11 * Windows: `%appdata%/Ferdi/recipes/<recipe id>/`
22 * Linux: `~/.config/Ferdi/recipes/<recipe id>` 12 * Linux: `~/.config/Ferdi/recipes/<recipe id>`
23 13
14> If you can't find the recipe's folder, please make sure that you have created a service inside Ferdi with that recipe - otherwise Ferdi will not load it into the folder
15
24After changing the files in that folder, you can reload the service inside Ferdi using `CTRL/CMD + R`. 16After changing the files in that folder, you can reload the service inside Ferdi using `CTRL/CMD + R`.
25 17
26## 2. Setting up the recipe repository 18## 2. Setting up the recipe repository
27 19
28- Fork https://github.com/getferdi/recipes and clone it to your computer 20Simply fork https://github.com/getferdi/recipes. You may also want to clone the repository to your computer to edit it locally.
29- Open a terminal in the `scripts/` folder of that repository
30- Run `npm install` to install all dependencies
31
32This will setup the repository so that you can work on updating it.
33 21
34## 3. Loading and updating the recipe 22## 3. Updating the recipe inside the repository
35 23
36Again, please **do not** edit any of the files located inside the `uncompressed` folder! Before editing, you'll need to "load" the recipe you want to edit using 24Simply add your changes to the recipe inside this repository.
37```JavaScript
38npm run load <recipe id>
39```
40(e.g. `npm run load gmail`)
41
42Your recipe is now loaded into `scripts/recipe_src`. You can now make changes to the files **in that folder*.
43 25
44## 4. Updating the version number 26## 4. Updating the version number
45 27
46In order for Ferdi to update its recipe, you'll need to bump its version number. Increase the `version` inside `scripts/recipe_src/package.json`. 28This might be the __most important step__ of this guide. You'll need to increase the version number inside recipe's `package.json`.
47
48## 5. Re-packaging the recipe
49 29
50You can now run `npm run package` to repackage your updated files. Your changes will be automatically copied into the recipe source at `uncompressed` and compressed into `archives/<recipe id>.tar.gz` - no need to update anything manually! 30Ferdi uses this version to determine if it should update the local copy of the recipe. If you do not increase the version number, no Ferdi user will get your updated recipe 😔
51 31
52## 6. Commit your changes and create a PR to <https://github.com/getferdi/recipes> 32## 5. Commit your changes and create a PR to <https://github.com/getferdi/recipes>