|
1 | | -# Before submitting your contribution, please read the following: |
| 1 | +# Contributing Guide |
| 2 | +This guide will tell you how you can and should contribute to JokeAPI. |
| 3 | +Not following it might cause me to reject your changes but at the very least we will both lose time. |
| 4 | +So please read this guide before contributing. Thanks :) |
| 5 | + |
| 6 | +## Menu: |
| 7 | +- [Submitting or editing jokes](#submitting-or-editing-jokes) |
| 8 | +- [Contributing to JokeAPI's code](#submitting-code) |
| 9 | +- [Submitting a translation](#submitting-translations) |
| 10 | +- [Tips and Tricks for contributing](#other-nice-to-know-stuff) |
| 11 | + |
| 12 | +<br><br><br><br> |
| 13 | + |
| 14 | +## Submitting or editing jokes: |
| 15 | +To submit a joke manually, you can use the form on [this page.](https://sv443.net/jokeapi/v2/#submit) |
| 16 | +To submit it through code, you can make use of the ["submit" endpoint.](https://sv443.net/jokeapi/v2/#submit-endpoint) |
| 17 | + |
| 18 | +If you instead want to *edit* a joke, you can find them in the `jokes-xy.json` files in [`data/jokes/`](../data/jokes/) |
| 19 | +Please then follow the [code contribution section](#submitting-code) as well. |
| 20 | + |
| 21 | +<br><br> |
| 22 | + |
| 23 | +## Submitting code: |
2 | 24 | 1. [Read the Code_of_Conduct.md file](./Code_of_Conduct.md) (TLDR: just behave in a friendly manner). |
3 | 25 | 2. [Click here](https://github.com/Sv443/JokeAPI/fork) to fork the repository. Afterwards, clone or download it and locate the folder where it is contained. |
4 | 26 | 3. Make the changes you want to make to the code. |
|
7 | 29 | - `npm run validate-ids` to verify that all jokes have the correct ID. |
8 | 30 | - `npm run lint` to check the code for any warnings or errors. |
9 | 31 | 5. Run JokeAPI locally by running the command `node JokeAPI`, request some jokes and test the areas you modified / added to make sure everything still works. |
10 | | -6. Add yourself to the `contributors` object in the file `package.json` :) |
11 | | - - **If it doesn't exist or is empty** please add it using the second format on [this website](https://flaviocopes.com/package-json/#contributors) |
| 32 | +6. Add yourself to the `contributors` object in the [`package.json`](../package.json) file :) |
| 33 | + <!-- - **If it doesn't exist or is empty** please add it using the second format on [this website](https://flaviocopes.com/package-json/#contributors) --> |
12 | 34 | 7. Submit a pull request on your forked repository, selecting `Sv443/JokeAPI` as the base repo and `master` as the base branch and selecting `YourUsername/JokeAPI` as the head repo and `YourBranch` as the compare branch |
13 | 35 | - If your pull request is not ready to be merged yet, you can add `[WIP]` to the beginning of the title which will tell the repo maintainer(s) and automated scripts not to merge it yet. |
14 | 36 | 8. Request a review from me (Sv443). |
|
19 | 41 |
|
20 | 42 | <br><br> |
21 | 43 |
|
22 | | -### Other nice-to-know stuff: |
| 44 | +## Submitting Translations: |
| 45 | +If you want to submit a translation, please follow these steps: |
| 46 | +1. Find your language's two-character code in the file [`data/languages.json`](../data/languages.json). You'll need to specify it for every translation. |
| 47 | +2. Translate coded error messages in the file [`data/errorMessages.js`](../data/errorMessages.js) by following the style of the other translations. |
| 48 | +3. Translate the generic strings inside of the file [`data/translations.json`](../data/translations.json) by also following the style of the other translations. |
| 49 | +4. Add yourself to the `contributors` object in the [`package.json`](../package.json) file :) |
| 50 | + |
| 51 | +<br><br> |
| 52 | + |
| 53 | +## Other nice-to-know stuff: |
23 | 54 | - I really recommend using [Visual Studio Code](https://code.visualstudio.com/) with the extension [`fabiospampinato.vscode-highlight`](https://marketplace.visualstudio.com/items?itemName=fabiospampinato.vscode-highlight) - it will add custom styling to the syntax highlighting in the editor and make the code easier to read and work with. |
24 | | -- If you want to generate a dependency graph, you need to install [Graphviz](https://graphviz.gitlab.io/download/) and add the path to the `bin` folder to your `%PATH%` environment vaiable. Then, run the command `npm run dependency-graph` and open the file `./dev/dependency-graph.html` in a browser. |
25 | | -- If you need to add an authorization token, you can generate one or multiple tokens with the command `npm run add-token [amount]`. If you omit the "amount" parameter, the script will generate a single token. After you run the command, the tokens will be listed in the console and you can now (after restarting JokeAPI) use it in the `x-api-token` header to gain unlimited access to JokeAPI. |
| 55 | +- If you want to generate a dependency graph, you need to install [Graphviz](https://graphviz.gitlab.io/download/) and add the path to the `bin` folder to your `%PATH%` / `$PATH` environment vaiable. Then, run the command `npm run dependency-graph` and open the file [`dev/dependency-graph.html`](../dev/dependency-graph.html) in a browser. |
| 56 | +- If you need to add an authorization token, you can generate one or multiple tokens with the command `npm run add-token [amount]`. If you omit the "amount" parameter, the script will generate a single token. After you run the command, the tokens will be listed in the console and you can now (after restarting JokeAPI) use it in the `Authorization` header to gain unlimited access to JokeAPI. |
| 57 | + |
| 58 | +<br><br> |
26 | 59 |
|
27 | | -## If you need any help, please feel free to contact me through [Discord](https://sv443.net/discord) or [E-Mail](mailto:sven.fehler@web.de?subject=Questions%20about%20contributing%20to%20JokeAPI) |
| 60 | +## If you need any help, feel free to contact me through [Discord](https://sv443.net/discord) (fastest way to contact me) or [E-Mail](mailto:contact@sv443.net?subject=Questions%20about%20contributing%20to%20JokeAPI) |
0 commit comments