Added initial contributing and development guides

This commit is contained in:
Eric Allam
2022-04-29 11:15:04 +01:00
parent d9cb941ed8
commit 0355b210af
3 changed files with 126 additions and 1 deletions
+41
View File
@@ -0,0 +1,41 @@
## ⚡️ JSON Hero Contributing Guide
First of all, thanks for considering contributing to this project! If you have any questions please don't hesitate to reach out to [eric@jsonhero.io](mailto:eric@jsonhero.io) or join us on [Discord](https://discord.gg/ZQq6Had5nP).
JSON Hero is a Typescript React application built with [remix.run](https://remix.run), with support for deploying to Cloudflare workers.
To get started with contributing, please read our [Development guide](https://github.com/jsonhero-io/jsonhero-web/blob/main/DEVELOPMENT.md) first to get JSON Hero running locally.
### Running tests
Although there is less test-coverage for JSON Hero than there should be, tests should still be run to ensure builds have not been broken:
```bash
npm test
```
You can also run tests in "watch" mode:
```bash
npm run test:watch
```
### Making changes
Please make any changes to your forked repository in a branch other than `main`. If you are working on a bug fix, please use the `bug/` prefix for your branch name. If you are working on a feature, please use `features/`. If you are working on a specific issue please name the branch `issue-<issue number>`
Make sure to run the `npm lint` command to ensure there are no Typescript compile-time errors.
### Pull Requests
Please open a Pull Request against the `main` branch in the `jsonhero-io/jsonhero-web` repository. We will aim to address all newly opened PRs by the following Friday. If you haven't opened a Pull Request before, please check out GitHub's [Pull Request documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests)
### Other JSON Hero projects
If you'd like to contribute to the [VSCode extension](https://marketplace.visualstudio.com/items?itemName=JSONHero.jsonhero-vscode), please see the [jsonhero-io/vscode-extension](https://github.com/jsonhero-io/vscode-extension) repo.
For issues related to the JSON Schema inference, please check out [jsonhero-io/schema-infer](https://github.com/jsonhero-io/schema-infer).
The "Smart Preview" feature is in-part powered by the [@jsonhero/json-infer-types](https://github.com/jsonhero-io/json-infer-types) project.
If it's related to the Search functionality, please see the [jsonhero-io/fuzzy-json-search](https://github.com/jsonhero-io/fuzzy-json-search) repo.
+83
View File
@@ -0,0 +1,83 @@
## 👩🏽‍💻 JSON Hero Local Development Guide
Welcome to JSON Hero development and thanks for being here! If you'd like to run JSON Hero locally, please use the following guide to get started. If you have any issues with this guide please feel free to email me at [eric@jsonhero.io](mailto:eric@jsonhero.io) or come leave a message in our open [Discord Channel](https://discord.gg/ZQq6Had5nP).
For more information about contributing to JSON Hero please see the [Contributing doc](https://github.com/jsonhero-io/jsonhero-web/blob/main/CONTRIBUTING.md).
### Install dependencies
Before you can run JSON Hero locally, you will need to install the following dependencies on your machine:
#### Git
You most likely already have git installed on your machine, but if not, you can install it from the [Git website](https://git-scm.com).
#### Node.js 16
Even though JSON Hero runs on [Cloudflare Workers](https://workers.cloudflare.com), which isn't a Node.js environment, you will still need Node.js 16 to run it locally. The recommended way to install Node.js is to download a pre-built package from the [Node.js website](https://nodejs.org/en/)
#### NPM
If you install Node.js through the above link, you should also have NPM automatically installed as well. To make sure, run the following command in your preferred Terminal:
```bash
npm ---version
```
### Fork JSON Hero on GitHub (optional)
To contribute code to JSON Hero, you should first create a fork of the [jsonhero-web](https://github.com/jsonhero-io/jsonhero-web) repository on GitHub. Follow [these instructions](https://docs.github.com/en/get-started/quickstart/fork-a-repo) on repository forking.
### Clone the repo
In your terminal, issue the following command to clone the repository to your local machine:
```bash
git clone https://github.com/jsonhero-io/jsonhero-web.git
```
Or if you've forked the repository:
```bash
git clone https://github.com/<github username>/jsonhero-web.git
```
Then `cd` into the repository:
```bash
cd jsonhero-web
```
### Prepare the repo
First, install npm dependencies:
```bash
npm install
```
Run the following command to create the `.env` file with a new `SESSION_SECRET` environment variable:
```bash
echo "SESSION_SECRET=$(openssl rand -hex 32)" > .env
```
Start the development server:
```bash
npm start
```
You should now be able to access your local JSON Hero server on [localhost:8787](http://localhost:8787)
> **Note** JSON documents created locally are not persisted across server restarts
### Previewing URLs
We currently use [Peekalink](https://www.peekalink.io) to power some of the Preview URL functionality. This feature is disabled unless there is a valid `PEEKALINK_API_KEY` environment variable set in your `.env` file created above.
If you'd like to enable this functionality locally, signup for Peekalink and set the `PEEKALINK_API_KEY`
### Deploying to Cloudflare
_Coming Soon_
+2 -1
View File
@@ -24,7 +24,8 @@
"test:watch": "jest --watch",
"test:coverage": "jest --coverage",
"build:types": "tsc",
"build:types:watch": "tsc --watch"
"build:types:watch": "tsc --watch",
"lint": "npm run build:types"
},
"dependencies": {
"@codemirror/lang-json": "^0.19.1",