diff options
author | 2020-04-02 17:31:21 +0200 | |
---|---|---|
committer | 2020-04-02 17:31:21 +0200 | |
commit | ac582422d821edb614608cd8256f9f48efcf52d7 (patch) | |
tree | 0198a09e9af5f8e56c3b1a92c56453a0563b7ebe | |
parent | Fix habitica logo (diff) | |
download | ferdium-recipes-ac582422d821edb614608cd8256f9f48efcf52d7.tar.gz ferdium-recipes-ac582422d821edb614608cd8256f9f48efcf52d7.tar.zst ferdium-recipes-ac582422d821edb614608cd8256f9f48efcf52d7.zip |
Add docs about updating existing recipes
-rw-r--r-- | docs/README.md | 1 | ||||
-rw-r--r-- | docs/integration.md | 2 | ||||
-rw-r--r-- | docs/updating.md | 52 |
3 files changed, 55 insertions, 0 deletions
diff --git a/docs/README.md b/docs/README.md index 689ecd5..b741e63 100644 --- a/docs/README.md +++ b/docs/README.md | |||
@@ -2,6 +2,7 @@ | |||
2 | Create your own [Ferdi](https://getferdi.com) service integration within a few minutes. | 2 | Create your own [Ferdi](https://getferdi.com) service integration within a few minutes. |
3 | 3 | ||
4 | * [Overview / How to create a Ferdi integration](integration.md) | 4 | * [Overview / How to create a Ferdi integration](integration.md) |
5 | * [How to update/change recipes](updating.md) | ||
5 | * [Configuration (package.json)](configuration.md) | 6 | * [Configuration (package.json)](configuration.md) |
6 | * [Frontend API (webview.js)](frontend_api.md) | 7 | * [Frontend API (webview.js)](frontend_api.md) |
7 | * [Backend API (index.js)](backend_api.md) | 8 | * [Backend API (index.js)](backend_api.md) |
diff --git a/docs/integration.md b/docs/integration.md index 7b936aa..c75fa7a 100644 --- a/docs/integration.md +++ b/docs/integration.md | |||
@@ -6,6 +6,8 @@ A Ferdi recipe is basically nothing else than a node module and is currently ini | |||
6 | 6 | ||
7 | > ℹ️ 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. | 7 | > ℹ️ 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. |
8 | 8 | ||
9 | > If you want to update an existing recipe, please refer to <updating.md> instead | ||
10 | |||
9 | ## Table of Contents | 11 | ## Table of Contents |
10 | - [Ferdi Recipe Documentation / Overview](#ferdi-recipe-documentation--overview) | 12 | - [Ferdi Recipe Documentation / Overview](#ferdi-recipe-documentation--overview) |
11 | - [Table of Contents](#table-of-contents) | 13 | - [Table of Contents](#table-of-contents) |
diff --git a/docs/updating.md b/docs/updating.md new file mode 100644 index 0000000..afb29da --- /dev/null +++ b/docs/updating.md | |||
@@ -0,0 +1,52 @@ | |||
1 | # How to update/change recipes | ||
2 | |||
3 | If you want to improve or update an existing recipe, please follow this guide. | ||
4 | |||
5 | Please **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 | |||
9 | Before 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 | |||
11 | To find the recipe ID, you can search <https://github.com/getferdi/recipes/blob/master/all.json> for the recipe you want to edit. | ||
12 | |||
13 | In the rest of this guide, always replace "<recipe id>" with the ID of the recipe you want to edit. | ||
14 | |||
15 | 1. Implement your updates | ||
16 | |||
17 | We 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. | ||
18 | |||
19 | You can find the recipe source Ferdi uses at: | ||
20 | * Mac: `~/Library/Application Support/Ferdi/recipes/<recipe id>/` | ||
21 | * Windows: `%appdata%/Ferdi/recipes/<recipe id>/` | ||
22 | * Linux: `~/.config/Ferdi/recipes/<recipe id>` | ||
23 | |||
24 | After changing the files in that folder, you can reload the service inside Ferdi using `CTRL/CMD + R`. | ||
25 | |||
26 | 2. Setting up the recipe repository | ||
27 | |||
28 | - Fork https://github.com/getferdi/recipes and clone it to your computer | ||
29 | - Open a terminal in the `scripts/` folder of that repository | ||
30 | - Run `yarn install` to install all dependencies | ||
31 | |||
32 | This will setup the repository so that you can work on updating it. | ||
33 | |||
34 | 3. Loading and updating the recipe | ||
35 | |||
36 | Again, 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 | ||
37 | ```JavaScript | ||
38 | yarn load <recipe id> | ||
39 | ``` | ||
40 | (e.g. `yarn load gmail`) | ||
41 | |||
42 | Your recipe is now loaded into `scripts/recipe_src`. You can now make changes to the files **in that folder*. | ||
43 | |||
44 | 4. Updating the version number | ||
45 | |||
46 | In order for Ferdi to update its recipe, you'll need to bump its version number. Increase the `version` inside `scripts/recipe_src/package.json`. | ||
47 | |||
48 | 5. Re-packaging the recipe | ||
49 | |||
50 | You can now run `yarn 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! | ||
51 | |||
52 | 6. Commit your changes and create a PR to <https://github.com/getferdi/recipes> | ||