urbit/pkg/interface/CONTRIBUTING.md

Introduction

Thanks for your interest in contributing to the Urbit interface. This section specifically focuses on Landscape development. Landscape lets you integrate your ship with front-end web applications accessed through the browser. It has a core set of applications that accept contributions.

Related to Landscape is Gall, the Arvo vane that controls userspace applications. Landscape applications will usually make good use of Gall, but it's not strictly required if a Landscape application is not interacting with ships directly.

Create a development ship, then once your ship is running, mount to Unix with |mount %. This will create a folder named 'home' in your pier in Unix. The 'home' desk contains the working state of your ship -- like a Git repository, when you want to make a change to it, |commit %home.

Contributing to Landscape applications

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 instructions 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/urbitwill 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) 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.

Linting

The Urbit interface uses Eslint to lint the JavaScript code. To install the linter and for usage through the command, do the following:

$ cd ./pkg/interface
$ npm install
$ npm run lint

To use the linter, run npm scripts

$ npm run lint # lints all files in `interface`
$ npm run lint-file ./chat/**/*.js # lints all .js files in `interface/chat`
$ npm run lint-file ./chat/src/index.js # lints a single chosen file

Gall

Presently, Gall documentation is still in progress, but a good reference. For examples of Landscape apps that use Gall, see the code for Chat and Publish.

Creating your own applications

If you'd like to create your own application for Landscape, the easiest way to get started is using the create-landscape-app repository template. It provides a brief wizard when you run it with npm start, and has good documentation for its everyday use -- just create a repo using its template, install and then start it, and you'll soon be up and running.