Merge pull request #3 from hydra-synth/guide-dev

code dev guides draft

content/docs/learning/guides/_index.md

@@ -24,4 +24,10 @@ Deeper dives into hydra topics written by members of the hydra community.
 * hydra + p5
 * hydra + THREE.js
 * hydra + AFrame
-#### Live performance
+#### Live performance
+
+#### Developing and Contributing
+* [overview](contributing)
+* [hydra-synth](contributing/synth)
+* [hydra-editor](contributing/editor)
+* [hydra-server](contributing/server)

content/docs/learning/guides/contributing/_index.md

@@ -0,0 +1,30 @@
+---
+bookCollapseSection: true
+weight: 7
+title: "developing and contributing"
+---
+
+# Developing and Contributing
+
+In this guide, you will learn how to "compile" hydra, to test your own version, and to contribute to the original repository. This guide is for those who are familar with JavaScript to edit the code base. Knowledge of command line and front-end tools is preferred but we try to guide you step by step.
+
+## Understanding the structure
+
+Hydra consists of mainly 4 repositories:
+
+* [hydra](https://github.com/hydra-synth/hydra)
+* [hydra-synth](https://github.com/hydra-synth/hydra-synth)
+* [hydra-server](https://github.com/hydra-synth/hydra-server)
+* [l10n](https://github.com/hydra-synth/l10n)
+
+hydra, or hydra-editor, is the webpage that comes with the editor. If you want to make changes in, e.g., the behavior of the editor, this is the right repository. We will look into detail in [developing editor](editor).
+
+hydra-synth is the "engine" that processes your hydra code on the editor and produces GLSL (shader) code. We explain in detail in [developing synth](synth).
+
+hydra-server is a backend program for signaling and storing the gallery. Note that you don't need this for testing the editor. We explain in detail in [developing backend server](server).
+
+l10n is a collection of locale files, i.e., translations for the editor interface. If you want to contribute translations, please refer to this [doc](https://github.com/hydra-synth/hydra-docs/blob/main/contributing_translation.md#hydra-editor).
+
+## All contributors
+
+Thank you to everyone who contributed to the project, not only contributing the code, but including reporting bugs, organizing events, and making tutorials, etc! We would like to acknowledge everyone who contributes to make hydra better. Please submit your information [here](https://github.com/hydra-synth/hydra/issues/265).

content/docs/learning/guides/contributing/editor.md

@@ -0,0 +1,90 @@
+---
+bookCollapseSection: true
+weight: 7
+title: "developing editor"
+---
+
+# Developing editor
+
+To run locally, you must have nodejs and npm installed. Install node and npm from: https://nodejs.org/en/.
+
+First, clone the repository
+
+    git clone [email protected]:hydra-synth/hydra.git
+
+enter the directory of the hydra source code:
+
+    cd hydra
+
+## Current main branch
+
+The current `main` branch uses browserify to bundle the script. While new features should be implemented in dev branch, if there is a hot fix needed in the current `main` branch, please follow this guide.
+
+Once you have node and npm installed, you can install yarn globally by running the following from the command line:
+
+    npm install --global yarn
+
+install dependencies:
+
+    yarn install
+
+bundle JavaScript with browserify:
+
+    yarn build
+
+run server
+
+    yarn serve
+
+go to <http://localhost:8000> in the browser. Congratulations! You built hydra-editor on your computer!
+
+### Where do these commands come from?
+
+Yarn commands are defined in `package.json`.
+
+### Development
+
+Make your new branch
+
+    git checkout -b my-awesome-feature
+
+Edit the code. If you want to see changes in real time, you can use the watch script. After running `yarn serve`, open another terminal and run
+
+    yarn watch
+
+Then every time you save code, it will automatically re-bundle the code.
+
+### Serving on your own server
+
+(stub)
+
+### Commit, push and pull request
+
+(stub)
+
+## dev branch
+
+New features should be implemented in `dev` branch. [After entering the directory](#developing-editor), checkout the branch
+
+    git checkout -b dev origin/dev
+
+install dependencies:
+
+    npm install
+
+run dev environment
+
+    npm run dev
+
+Since we use vite in `dev` branch, we don't need to bundle the code during development (vite takes care of bundling and serving while you code). When you want to publish the code, build the bundle:
+
+    npm run build
+
+
+### Connecting to server from dev/ local editor environment
+This repo only contains hydra editor frontend. You can connect to a backend server (https://github.com/hydra-synth/hydra-server) for signaling and gallery functionality. To do this, set up hydra-server from above. Then create a `.env` file in the root of the `hydra` directory. Add the url of your server as a line in the .env file as:
+```
+VITE_SERVER_URL=http://localhost:8000
+```
+(replace http://localhost:8000 with the url of your server)
+

content/docs/learning/guides/contributing/server.md

@@ -0,0 +1,9 @@
+---
+bookCollapseSection: true
+weight: 7
+title: "developing backend server"
+---
+
+# Developing backend server
+
+(stub)

content/docs/learning/guides/contributing/synth.md

@@ -0,0 +1,47 @@
+---
+bookCollapseSection: true
+weight: 7
+title: "developing hydra-synth"
+---
+
+# Developing synth
+
+Clone the repository
+
+    [email protected]:hydra-synth/hydra-synth.git
+
+enter the folder
+
+    cd hydra-synth
+
+install the dependencies
+
+    npm install
+
+build
+
+    npm run build
+
+The bundled code is in `dist/hydra-synth.js`.
+
+## Trying on the browser
+
+This repository does not come with the editor. However, you can use the simple example `dist/index.html`. To do so, install `http-server`
+
+    npm install --global http-server
+
+and serve `dist` folder
+
+    http-server dist
+
+go to <http://localhost:8000> in the browser. You can either edit the hydra code in `index.html` to try hydra functions, or open the developer console and type hydra code (e.g., `osc().out()`) and it will update the canvas. The former is useful for testing more complex examples including non-global mode, and the later is useful for quick testing.
+
+For testing the integration with hydra-editor (of if you want to host your own hydra version on your server), please follow [editor guide](editor) to host your own editor. Then, edit `package.json` in **hydra** (not hydra-synth) to use the local version of hydra-synth (assuming you have hydra and hydra-synth folders in the same folder)
+
+    "hydra-synth": "file:../hydra-synth",
+
+Then in hydra, update the package
+
+    npm update hydra-synth
+
+Now the editor is using your version of hydra-synth.