mirror of
https://github.com/ilyakooo0/urbit.git
synced 2025-01-04 13:19:48 +03:00
Merge branch 'mp/meta/contributing-revision' (#3615)
* origin/mp/meta/contributing-revision: meta: add dev ship instructions from master meta: simplify interface contributing Signed-off-by: Matilde Park <matilde.park@sunshinegardens.org>
This commit is contained in:
Matilde Park
commit
eb0cda8410
@ -38,6 +38,17 @@ To resume a fake ship, just pass the name of the pier:
|
||||
$ urbit my-fake-zod
|
||||
```
|
||||
|
||||
Fake ships by default use the same pre-compiled kernelspace ('pills') as livenet
|
||||
ships do: boot pills, which are not always current with `master`. If you wish to
|
||||
develop using code off the master branch, run the following from the repo
|
||||
directory:
|
||||
|
||||
```
|
||||
git lfs install
|
||||
git lfs pull
|
||||
urbit -F zod -B "bin/solid.pill" -A "pkg/arvo"
|
||||
```
|
||||
|
||||
## Git practice
|
||||
|
||||
### Contributing
|
||||
|
||||
@ -10,11 +10,12 @@ 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.
|
||||
|
||||
## Contributing to Landscape applications
|
||||
## Starting the dev environment
|
||||
|
||||
To begin developing on Landscape, find the `urbitrc-sample` file found
|
||||
at `urbit/pkg/interface/config/urbitrc-sample`. Copy it as `urbitrc`.
|
||||
Open it using your preferred code editor and you should see the following:
|
||||
From this directory, go to the config folder and copy `urbitrc-sample` to
|
||||
`urbitrc`.
|
||||
|
||||
You should see the following:
|
||||
|
||||
```
|
||||
module.exports = {
|
||||
@ -26,130 +27,17 @@ module.exports = {
|
||||
};
|
||||
```
|
||||
|
||||
This file is the configuration file for your front-end development environment.
|
||||
Let's walk through it.
|
||||
|
||||
The first line, listing piers, specifies which piers to copy the JS files into.
|
||||
By default, the development environment won't copy files into any pier, even if
|
||||
you've set the pier in `urbitrc`.
|
||||
|
||||
If you want to copy the JS files into your ship, as it would run in a regular
|
||||
user environment, uncomment these lines in
|
||||
`pkg/interface/config/webpack.dev.js`:
|
||||
|
||||
```javascript
|
||||
// uncomment to copy into all piers
|
||||
//
|
||||
// return Promise.all(this.piers.map(pier => {
|
||||
// const dst = path.resolve(pier, 'app/landscape/js/index.js');
|
||||
// copyFile(src, dst).then(() => {
|
||||
// if(!this.herb) {
|
||||
// return;
|
||||
// }
|
||||
// pier = pier.split('/');
|
||||
// const desk = pier.pop();
|
||||
// return exec(`herb -p hood -d '+hood/commit %${desk}' ${pier.join('/')}`);
|
||||
// });
|
||||
// }));
|
||||
```
|
||||
|
||||
And then set your pier in `urbitrc` (ensure it ends in `/home`). The `herb`
|
||||
option in your `urbitrc` will automatically commit the changes to your ship if
|
||||
you have herb installed (see `pkg/herb`).
|
||||
|
||||
For most developers, if you are making changes to Landscape without any back-end
|
||||
changes on the Urbit ship itself, and you have an Urbit ship running already,
|
||||
you don't have to boot a development ship. You can simply set up the dev server
|
||||
for the development environment and point it at your running ship.
|
||||
|
||||
To do this, set the `URL` property in your urbitrc and replace it with the URL
|
||||
of the urbit that you are testing on. For example, a development ship by default
|
||||
lives at `localhost:80` so our `urbitrc` would have:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
URL: 'http://localhost:80'
|
||||
}
|
||||
```
|
||||
|
||||
Then get everything installed:
|
||||
Change the URL to your livenet ship (if making front-end changes) or keep it the
|
||||
same (if [developing on a local development ship][local]). Then, from
|
||||
'pkg/interface':
|
||||
|
||||
```
|
||||
## go to urbit's interface directory and install the required tooling
|
||||
cd urbit/pkg/interface
|
||||
npm install
|
||||
|
||||
## Start your development server
|
||||
npm run start
|
||||
```
|
||||
|
||||
You can then access a hot reloaded version of the interface at
|
||||
`http://localhost:9000`.
|
||||
|
||||
If you set the URL to your running ship, like
|
||||
`http://sampel-palnet.arvo.network`, then you can use your actual ship while
|
||||
running local-only development changes.
|
||||
|
||||
As previously stated, if your changes require back-end development (front-end
|
||||
and Gall changes, for example), or you just want an empty development
|
||||
environment, you'll want to create a development ship.
|
||||
|
||||
### Creating a development ship
|
||||
|
||||
[nix](https://github.com/NixOS/nix) and `git-lfs` should be installed at this
|
||||
point, and have been used to `make build` the project.
|
||||
|
||||
First follow the
|
||||
[instructions](https://urbit.org/using/develop/#creating-a-development-ship) for
|
||||
fake `~zod` initialization.
|
||||
|
||||
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 set up urbit's Javascript environment, you'll need node (ideally installed
|
||||
via [nvm](https://github.com/nvm-sh/nvm)) and webpack, which will be installed
|
||||
via node.
|
||||
|
||||
If you want to copy the code into your ship, perform the following steps:
|
||||
|
||||
```
|
||||
## go to urbit's interface directory and install the required tooling
|
||||
cd urbit/pkg/interface
|
||||
npm install
|
||||
|
||||
## Build the JS code
|
||||
npm run build:dev
|
||||
```
|
||||
|
||||
If you want to run the JavaScript code in a dev server, you can simply set the
|
||||
URL in your `urbitrc` to `localhost:80` and `npm run start` instead.
|
||||
|
||||
If you set your pier in `urbitrc`, and uncommented the code in the webpack
|
||||
config, then once the build process is running, commit on your ship to copy the
|
||||
changed JS code in:
|
||||
|
||||
```
|
||||
|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 your
|
||||
process. Do not commit compiled code, but submit the source code
|
||||
for review.
|
||||
|
||||
Please also ensure your pull request fits our standards for [Git
|
||||
hygiene][contributing].
|
||||
|
||||
[contributing]: /CONTRIBUTING.md#git-practice
|
||||
[arvo]: /pkg/arvo
|
||||
[interface]:/pkg/interface
|
||||
The dev server will start at `http://localhost:9000`. Sign in as you would
|
||||
normally. Landscape will refresh automatically as you make changes.
|
||||
|
||||
## Linting
|
||||
|
||||
@ -170,12 +58,6 @@ $ npm run lint-file ./src/apps/chat/**/*.js # lints all .js files in `interface/
|
||||
$ npm run lint-file ./src/chat/app.js # lints a single chosen file
|
||||
```
|
||||
|
||||
### 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
|
||||
@ -188,5 +70,4 @@ 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-view.hoon
|
||||
[publish]: /pkg/arvo/app/publish.hoon
|
||||
[local]: /CONTRIBUTING.md#fake-ships
|
||||
Loading…
Reference in New Issue
Block a user