diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 980cbc967..2183c5400 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,9 +4,11 @@ Thank you for your interest in contributing to urbit. See [urbit.org/docs/getting-started][start] for basic orientation and usage instructions. You may also want to subscribe to [urbit-dev][list], the urbit -development mailing list. +development mailing list. For specific information on contributing to the urbit +interface, see its [contribution guidelines][interface]. [start]: https://urbit.org/docs/getting-started/#arvo +[interface]: /pkg/interface/CONTRIBUTING.md ## Fake ships diff --git a/pkg/interface/CONTRIBUTING.md b/pkg/interface/CONTRIBUTING.md new file mode 100644 index 000000000..e2a60bc48 --- /dev/null +++ b/pkg/interface/CONTRIBUTING.md @@ -0,0 +1,58 @@ +## 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][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 + +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. + +On your development ship, ensure you `|commit %home` to confirm 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. + +Please also ensure your pull request fits our standards for +[Git hygiene][contributing]. + +[contributing]: /CONTRIBUTING.md#git-practice +[arvo]: /pkg/arvo +[interface]:/pkg/interface + +### Gall + +Presently, Gall documentation is still in [progress][gall], but a good +reference. For examples of Landscape apps that use Gall, see the code for +[Chat][chat] and [Publish][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][cla] 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][template], install and then start it, and you'll soon be up and +running. + +[cla]: https://github.com/urbit/create-landscape-app +[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 \ No newline at end of file