JokeAPI-v2/.github/Contributing.md

Contributing Guide

This guide will tell you how you can and should contribute to JokeAPI.
Not following it might cause me to reject your changes but at the very least we will both lose time.
So please read this guide before contributing. Thanks :)

Table of Contents:

• Submitting or editing jokes
• Contributing to JokeAPI's code
• Submitting a translation
• Tips and Tricks for contributing

Submitting or editing jokes:

To submit a joke manually, you can use the form on this page.
To submit it through code, you can make use of the "submit" endpoint.

If you instead want to edit a joke yourself, you can find them in the jokes-xy.json files in data/jokes/
To submit your changes, create a pull request. Also make sure to follow the code contribution instructions.

If you want a joke to be edited or deleted, please submit a new issue here.
Keep in mind, though, that I will not remove jokes based on opinions as that would defeat the API's main purpose, to provide jokes for everyone's taste.

Submitting code:

1. Read the Code_of_Conduct.md file (TLDR: just behave in a friendly manner).
2. Click here to fork the repository. Afterwards, clone or download it and locate the folder where it is contained.
3. Make the changes you want to make to the code.
4. Run the script npm run all which will run these commands:
   • npm run validate-jokes to make sure all jokes are formatted correctly.
   • npm run validate-ids to verify that all jokes have the correct ID.
   • npm run lint to check the code for any warnings or errors.
   • npm run dep-graph to generate a new dependency graph.
   • npm run generate-changelog to generate a Markdown changelog out of the plaintext one.
   • npm run test, which runs the unit tests for JokeAPI. If you are colorblind, you can run the command npm run test-colorblind (will turn green into cyan and red into magenta).
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.
6. Add yourself to the contributors object in the package.json file :)
7. Submit a pull request on your forked repository, selecting Sv443-Network/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
   • 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.
8. Request a review from me (Sv443).
9. Check if the CI script and other checks for your pull request were successful (they can be found below the comments).
   • If they were unsuccessful: view the log, fix the errors, commit the code and push to the same branch. This will automatically update your pull request and re-run the checks.
10. Once the pull request is approved and merged, you can delete the source branch and your forked repo if you want to.
    
    • If it isn't, please read the comments from the reviewer(s) and make the necessary changes.
      

Submitting Translations:

If you want to submit a translation, please follow these steps:

1. Find your language's two-character code in the file data/languages.json. You'll need to specify it for every translation.
2. Translate coded error messages in the file data/errorMessages.js by following the style of the other translations.
3. Translate the generic strings inside of the file data/translations.json by also following the style of the other translations.
4. Add yourself to the contributors object in the package.json file :)

Other nice-to-know stuff:

• I really recommend using Visual Studio Code with the extension 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.
  
• If you want to generate a dependency graph, you need to install Graphviz 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 in a browser.
  
• 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 (better explanation here).
  

If you need any help, feel free to contact me through Discord (fastest way to contact me) or E-Mail