From 833ee2437767b768306bfcd1604e8d35b30b2c29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=A9douard?= Date: Mon, 2 Mar 2020 01:44:43 -0500 Subject: [PATCH 1/3] contributing.md: Added a new section outlining how to develop urbit's interface We have had a document floating around in gdocs for a while outlining how to actually contribute to urbit's frontend design/dev, but I figured this would actually be really good info to surface up in our Contributing guideline. I've minified the original doc to somewhat match the tone of this guide, but it could use an editorial pass (and accuracy check) from @jtobin , @loganallenc , and @matildepark . Please email me for a link to the original document, if you'd like to compare. --- CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be393a610..937885008 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -249,6 +249,78 @@ $ git lfs pull [git-lfs]: https://git-lfs.github.com +## Interface development + +Designing interfaces within urbit/urbit requires that the above steps for +fake `~zod` initialization are followed. Once your fake ship is running and you +see +``` +~zod:dojo> +``` +in your console, be sure to mount a desk to your local machine via the +`|mount %` command. This will ensure that code you modify locally can be +committed to your ship. + +To begin developing Urbit's frontend, you'll need to sync your +currently-running fake ship with the urbit/urbit repo's code. Find the +`urbitrc-sample` file found at `urbit/pkg/interface/urbitrc-sample`. Open it +using your preferred code editor and you should see the following: + +``` +module.exports = { + URBIT_PIERS: [ + "/Users/user/ships/zod/home", + ] +}; +``` + +Edit the path between quotes `/Users/user/ships/zod/home` with wherever your +fake ship is located on your machine. Any code edited within the `urbit/urbit` +will now be able to be synced to your running ship, and previewed in the +browser. + +To set up urbit's Javascript environment, you'll need node (ideally installed +via [nvm](https://github.com/nvm-sh/nvm)) and gulp, which will be installed +via node. + +Perform the following steps to get the above set up for urbit's apps: + +``` +## go to urbit's interface directory and install the required tooling +cd urbit/pkg/interface +npm install +npm install -g gulp + +## assuming you are still in `urbit/pkg/interface`, +## open a single app directory, and watch it for changes +cd contacts/ +gulp watch +``` + +Any changes made to any files within the `/contacts` directory will now +trigger a gulp rebuild when saved. To sync these changes to your running +ship, enter dojo and input the following: + +``` +|commit %home +``` + +Your urbit should take a moment to process the changes, and will emit a +`>=`. Refreshing your browser will display the newly-rendered interface. + +Once you are done editing code, and wish to commit changes to git, stop +`gulp watch` and run `gulp bundle-prod` to ensure you are only +committing 1 minified line of compiled js and not 3000+. + +An additional note: + +As compiled Javasscript is not present in the urbit/urbit repository, +you'll need to run `.sh/build-interface` in order to see changes that +have been committed to any given branch you might be working on. It's +always a good idea to run the above command before starting development +to ensure you can see collaborators' changes. + + ## Issues The [GitHub tracker][issu] is our canonical source of truth around issues, From 3b6f265cc00d59f774bdcbac5841aced1b2d511b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=A9douard?= Date: Mon, 2 Mar 2020 01:59:08 -0500 Subject: [PATCH 2/3] contributing.md: added more pre-req detail to the beginning of the edit Added information pertaining to nix and git-lfs installation required to work with urbit's interfaces. --- CONTRIBUTING.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 937885008..3e1feda76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -251,9 +251,13 @@ $ git lfs pull ## Interface development -Designing interfaces within urbit/urbit requires that the above steps for -fake `~zod` initialization are followed. Once your fake ship is running and you -see +[nix](https://github.com/NixOS/nix) and `git-lfs` should be installed at +this point, and have been used to `make build` the project. + +Designing interfaces within urbit/urbit additionally requires that the +above steps for fake `~zod` initialization have been followed. + +Once your fake ship is running and you see ``` ~zod:dojo> ``` From 6ed75204449efe3fdac4169bdee0b10eb5f283c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=A9douard?= Date: Fri, 3 Apr 2020 15:37:42 -0400 Subject: [PATCH 3/3] contributing.md: removed interface dev instructions from root-level doc, integrated into existing interface-specific doc I've moved the slightly edited interface development instructions from the root controbuting.md doc, over to the one located in pkg/interface. I've made sure to ensure any precvious information in the interface contributing doc has been matched or expanded upon in the new writing, which is a incrementally more thorough, and assumes a lower level of build-tooling knowledge. --- CONTRIBUTING.md | 76 -------------------------------- pkg/interface/CONTRIBUTING.md | 82 ++++++++++++++++++++++++++++++----- 2 files changed, 71 insertions(+), 87 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e1feda76..be393a610 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -249,82 +249,6 @@ $ git lfs pull [git-lfs]: https://git-lfs.github.com -## Interface development - -[nix](https://github.com/NixOS/nix) and `git-lfs` should be installed at -this point, and have been used to `make build` the project. - -Designing interfaces within urbit/urbit additionally requires that the -above steps for fake `~zod` initialization have been followed. - -Once your fake ship is running and you see -``` -~zod:dojo> -``` -in your console, be sure to mount a desk to your local machine via the -`|mount %` command. This will ensure that code you modify locally can be -committed to your ship. - -To begin developing Urbit's frontend, you'll need to sync your -currently-running fake ship with the urbit/urbit repo's code. Find the -`urbitrc-sample` file found at `urbit/pkg/interface/urbitrc-sample`. Open it -using your preferred code editor and you should see the following: - -``` -module.exports = { - URBIT_PIERS: [ - "/Users/user/ships/zod/home", - ] -}; -``` - -Edit the path between quotes `/Users/user/ships/zod/home` with wherever your -fake ship is located on your machine. Any code edited within the `urbit/urbit` -will now be able to be synced to your running ship, and previewed in the -browser. - -To set up urbit's Javascript environment, you'll need node (ideally installed -via [nvm](https://github.com/nvm-sh/nvm)) and gulp, which will be installed -via node. - -Perform the following steps to get the above set up for urbit's apps: - -``` -## go to urbit's interface directory and install the required tooling -cd urbit/pkg/interface -npm install -npm install -g gulp - -## assuming you are still in `urbit/pkg/interface`, -## open a single app directory, and watch it for changes -cd contacts/ -gulp watch -``` - -Any changes made to any files within the `/contacts` directory will now -trigger a gulp rebuild when saved. To sync these changes to your running -ship, enter dojo and input the following: - -``` -|commit %home -``` - -Your urbit should take a moment to process the changes, and will emit a -`>=`. Refreshing your browser will display the newly-rendered interface. - -Once you are done editing code, and wish to commit changes to git, stop -`gulp watch` and run `gulp bundle-prod` to ensure you are only -committing 1 minified line of compiled js and not 3000+. - -An additional note: - -As compiled Javasscript is not present in the urbit/urbit repository, -you'll need to run `.sh/build-interface` in order to see changes that -have been committed to any given branch you might be working on. It's -always a good idea to run the above command before starting development -to ensure you can see collaborators' changes. - - ## Issues The [GitHub tracker][issu] is our canonical source of truth around issues, diff --git a/pkg/interface/CONTRIBUTING.md b/pkg/interface/CONTRIBUTING.md index efbc190ab..334099115 100644 --- a/pkg/interface/CONTRIBUTING.md +++ b/pkg/interface/CONTRIBUTING.md @@ -17,17 +17,77 @@ when you want to make a change to it, `|commit %home`. ## Contributing to Landscape applications -If you'd like to contribute to the core set of Landscape applications in this -repository, clone this repository and start by creating an `urbitrc` file in -this folder, [pkg/interface][interface]. You can find an `urbitrc-sample` here -for reference. Then `cd` into the application's folder and `npm install` the -dependencies, then `gulp watch` to watch for changes. +[nix](https://github.com/NixOS/nix) and `git-lfs` should be installed at +this point, and have been used to `make build` the project. -On your development ship, ensure you `|commit %home` to apply your changes. -Once you're done and ready to make a pull request, running `gulp bundle-prod` -will make the production files and deposit them in [pkg/arvo][arvo]. Create a -pull request with both the production files, and the source code you were -working on in the interface directory. +Designing interfaces within urbit/urbit additionally requires that the [instructions](https://urbit.org/using/develop/#creating-a-development-ship) for fake `~zod` initialization have been followed. + +Once your fake ship is running and you see +``` +~zod:dojo> +``` +in your console, be sure to 'mount' your ship's working state (what we call 'desks') to your local machine via the +`|mount %` command. This will ensure that code you modify locally can be +committed to your ship and initialized. + +To begin developing Urbit's frontend, you'll need to sync your +currently-running fake ship with the urbit/urbit repo's code. Find the +`urbitrc-sample` file found at `urbit/pkg/interface/urbitrc-sample` (in this folder). Open it +using your preferred code editor and you should see the following: + +``` +module.exports = { + URBIT_PIERS: [ + "/Users/user/ships/zod/home", + ] +}; +``` + +Edit the path between quotes `/Users/user/ships/zod/home` with wherever your +fake ship is located on your machine. This zod location path *must* end in `../home` to correctly intitalize +any code you write. Any code edited within the `urbit/urbit`will now be able to be synced to your running +ship, and previewed in the browser. + +To set up urbit's Javascript environment, you'll need node (ideally installed +via [nvm](https://github.com/nvm-sh/nvm)) and gulp, which will be installed +via node. + +Perform the following steps to get the above set up for urbit's apps: + +``` +## go to urbit's interface directory and install the required tooling +cd urbit/pkg/interface +npm install +npm install -g gulp + +## assuming you are still in `urbit/pkg/interface`, +## open a single app directory, and watch it for changes +cd contacts/ +gulp watch +``` + +Any changes made to any files within the `/contacts` directory will now +trigger a gulp rebuild when saved. To sync these changes to your running +ship, enter dojo and input the following: + +``` +|commit %home +``` + +Your urbit should take a moment to process the changes, and will emit a +`>=`. Refreshing your browser will display the newly-rendered interface. + +Once you are done editing code, and wish to commit changes to git, stop +`gulp watch` and run `gulp bundle-prod` to ensure you are only +committing 1 minified line of compiled js and not 3000+. + +An additional note: + +As compiled Javascript is not present in the urbit/urbit repository, +you'll need to run `.sh/build-interface` in order to see changes that +have been committed to any given branch you might be working on. It's +always a good idea to run the above command before starting development +to ensure you can see collaborators' changes. Please also ensure your pull request fits our standards for [Git hygiene][contributing]. @@ -55,4 +115,4 @@ running. [template]: https://github.com/urbit/create-landscape-app/generate [gall]: https://urbit.org/docs/learn/arvo/gall/ [chat]: /pkg/arvo/app/chat.hoon -[publish]: /pkg/arvo/app/publish.hoon +[publish]: /pkg/arvo/app/publish.hoon \ No newline at end of file