ilyakooo0/urbit
1
0
Fork 0
mirror of https://github.com/ilyakooo0/urbit.git synced 2024-11-11 04:48:00 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'jt-contributing' (#1673)

Browse Source 
* jt-contributing:
  readme: update contributing info
  contributing: use parentheses instead of commas
  contributing / interface: 'confirm' -> 'apply'
  contributing: s/urbit/Urbit
  contributing: text fixup
  contributing: remove labelling discussion
  contributing: adds userspace information, links
  contributing: add hoon style guide link
  contributing: improve description.. description
  contributing: add 'issues' section
  contributing: add mailing list info to intro
  contributing: update kernel & pills section
  contributing: touch up code style section
  contributing: add git/release info

Signed-off-by: Jared Tobin <jared@tlon.io>
This commit is contained in:
Jared Tobin 2019-09-03 12:46:02 -02:30
commit 07d9581934
No known key found for this signature in database
GPG Key ID: 0E4647D58F8A69E4
3 changed files with 196 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

205
CONTRIBUTING.md
View File

@ -1,17 +1,20 @@
# Contributing to Urbit
Thank you for your interest in contributing to urbit.
Thank you for your interest in contributing to Urbit.
See [urbit.org/docs/getting-started][start] for basic orientation and usage
instructions.
instructions. You may also want to subscribe to [urbit-dev][list], the Urbit
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
You may have an identity on the live network, but doing all your development on
the live network would be cumbersome and unnecessary. Standard practice in
urbit development is to work on a fake `~zod`. Fake ships use deterministic
Urbit development is to work on a fake `~zod`. Fake ships use deterministic
keys (derived from the ship address) and don't talk to the live network. They
can talk to each other over the local loopback.
@ -35,68 +38,117 @@ $ urbit my-fake-zod
## Git practice
Since we use the GitHub issue tracker, it is helpful (though not required) to
contribute via a GitHub pull request. If you already know what you are doing,
skip down to the Style section.
### Contributing
Start by cloning the repository on your work machine:
The canonical source tree is located in the `master` branch at
[https://github.com/urbit/urbit][repo]. You should typically branch off of
`master` when commencing new work; similarly, when we pull in your
contribution, we'll do so by merging it to `master`.
Since we use GitHub, it's helpful (though not required) to contribute via a
GitHub pull request. You can also post patches to the [mailing list][list],
email them to maintainers, or request a maintainer pull from your tree directly
-- but note that some maintainers will be more receptive to these methods than
others.
### Hygiene
Commits should generally be relevant, atomic, and have descriptions formatted
in the following manner:
> component: short description
>
> long description
The 'component' is a short prefix of what area of the codebase the commit
applies to. If a commit patches `%gall`, for example, the description should
be prefixed by 'gall'. If it touches `:aqua`, it should be prefixed by 'aqua'.
If it touches multiple components, then separate these by commas, e.g. "gall,
aqua, ph" -- but note that this may be a warning that too many changes are
being packed into a single commit. The 'component' and 'short description'
combined should be no more than 50 characters.
A lengthier description is encouraged, where useful, but is not required.
Here's an example of our commit format, applied to a hypothetical commit:
> zuse: remove superfluous 'scup' and 'culm' types.
>
> %zuse includes definitions for 'scup' and 'culm', both of which are
> superfluous. 'scup' is simply (pair ship desk) and is used only in
> the definition of 'culm', a tagged union in which three of the four
> branches are commented out (i.e. are unused).
>
> This commit deletes 'scup' and 'culm' and refactors what little code
> made use of them.
If you're in doubt about how to format your commit descriptions, take a look at
the recent history and try to mimic the style that you can see others broadly
follow there.
When we say commits should be "atomic", we mean with respect to some distinct
logical unit, e.g. a type definition used across many files, or a single file,
or just a single function in a single file. Commits should be atomic at the
level of *code*, not of entire features. You don't have to squash your commits
into a single one that captures everything you're trying to do -- the history
will never make for pleasant bedtime reading, so focus instead on making your
commits useful for tools like `git-blame` and `git-bisect`.
Your contribution must apply cleanly to `master` in order to be considered
mergeable. You may want to regularly [rebase your changes][reba] onto `master`
in order to both clean up any intermediate "development" commits you make and
to ensure that you're up to date.
If you're making a GitHub pull request, it's good practice to make it from a
topic branch, rather than `master`, on your fork.
### Pills
Any contribution that touches the kernel (i.e., anything in `pkg/arvo/sys`),
should be accompanied by an updated [solid pill](#the-kernel-and-pills). Pills
are tracked in the repository via [git LFS][git-lfs].
Whenever you make a contribution to the kernel, please create a new solid pill
via:
```
$ git clone https://github.com/urbit/urbit
sh/update-solid-pill
```
And, additionally, fork the repository on GitHub by clicking the "Fork"
button. Add your fork as a remote:
and include it along with your contribution. You can either include it in the
same commit as your change, or, if you prefer, in a standalone commit (you will
see plenty of "pills: update solid" commits if you look through the history).
```
$ git remote add [username] https://github.com/[username]/urbit
```
## Releases
and set it as the default remote to push to:
We typically create releases by cherry picking appropriate commits from
`master` and tagging the result, so any given commit in `master` may not
actually be present in the latest release.
```
$ git config --local remote.pushDefault [username]
```
We perform updates by pushing releases over-the-air to `~zod` approximately
once per week, so any contribution that can be deployed OTA will usually find
its way onto the network pretty rapidly.
This is good practice for any project that uses git. You will pull
upstream branches from urbit/urbit and push to your personal urbit fork
by default.
Less frequently we release new Vere versions, which requires users to download
new binaries, and occasionally, while Urbit is still in early development, we
breach network continuity in order to release large changes that are difficult
to push out over-the-air. Contributions to Vere, or non-OTA-able updates to
Arvo, will find their way into releases before terribly long.
Next, start a new branch to do your work on. Normally you'll want to use the
`master` branch as your starting point:
## Code style
```
$ git checkout -b [branch name] master
```
Now you are free to do your work on this branch. When finished, you may
want to clean up your commits:
```
$ git rebase -i master
```
Then you can push to your public fork with `git push` and make a pull request
via the GitHub UI.
After your changes are merged upstream, you can delete your branch (via github
UI or `git push :[branch]` remotely, and with `git branch -d` locally).
## Style
The urbit project uses two-space indentation and avoids tab characters.
The Urbit project uses two-space indentation and avoids tab characters.
In C code, it should not be too difficult to mimic the style of the code
around you, which is just fairly standard K&R with braces on every
compound statement. One thing to watch out for is top-level sections in
source files that are denoted by comments and are actually indented one
level.
Hoon will be a less familiar language to many contributors. More details are
forthcoming; for now, the `%ford` vane (in
[`pkg/arvo/sys/vane/ford.hoon`][ford]) is some of the highest quality code in
the kernel.
[ford]: https://github.com/urbit/urbit/blob/master/pkg/arvo/sys/vane/ford.hoon
Hoon will be a less familiar language to many contributors. We've published
some [style guidelines for Hoon][hoon], but above all you should try to mimic
the style of the code around you. With regards to the style used throughout
the codebase: the more recently the code was written, the more standard and
accepted its style is likely to be.
## Kernel development
@ -138,23 +190,14 @@ You can boot a new ship from your local pill with `-B`:
$ urbit -F zod -B path/to/urbit.pill my-fake-zod
```
Pills are cached at `https://bootstrap.urbit.org` and are indexed by the first
10 characters of the `git` SHA1 of the relevant commit, i.e. as
`git-[sha1].pill`. The continuous integration build uploads these pills for
any successful build of a commit or pull request that affects the
`pkg/arvo/sys/` directory.
You can boot from one of these pills by passing the path to an Arvo working
copy with `-A` (and `-s` for *search*):
```
$ git clone https://github.com/urbit/urbit
$ urbit -F zod -sA urbit/pkg/arvo -s my-fake-zod
```
Release pills, i.e. those corresponding to vere releases, are cached at
`https://bootstrap.urbit.org` and are indexed by the vere version number, e.g.
`urbit-0.8.2.pill`.
Pills are also cached in version control via [git LFS][git-lfs]. You can find
the latest solid pill (as well as the latest so-called *brass* and *ivory*
pills) in the `bin/` directory at the repository root:
the latest solid pill, as well as the latest so-called *brass* and *ivory*
pills, in the `bin/` directory at the repository root. Note that you'll need
to initialise git LFS in order to check these pills out:
```
$ git lfs init
@ -163,17 +206,29 @@ $ git lfs pull
[git-lfs]: https://git-lfs.github.com
## What to work on
## Issues
If you are not thinking of contributing with a specific goal in mind, the
GitHub issue tracker is the first place you should look for ideas. Issues are
occasionally tagged with a priority and a difficulty; a good place to start is
on a low-difficulty or low-priority issue. Higher-priority issues are likely
to be assigned to someone -- if this is the case, then contacting that person
to coordinate before starting to work is probably a good idea.
The [GitHub tracker][issu] is our canonical source of truth around issues,
bugs, performance problems, feature requests, and so on. If you encounter any
issues when developing on Urbit, feel free to submit a report about it here.
There is also a "help wanted" tag for things that we are especially eager to
have outside contributions on. Check here first!
A good bug report, description of a crash, etc., should ideally be
*reproducible*, with clear steps as to how another developer can replicate and
examine your problem. That said, this isn't always possible -- some bugs
depend on having created a complicated or unusual state, or can otherwise
simply be difficult to trigger again (say, you encountered it in the last
continuity era).
Your issue should thus at a minimum be *informative*. The best advice here is
probably "don't write bad issues," where "bad" is a matter of judgment and
taste. Issues that the maintainers don't judge to be sufficiently useful or
informative may be closed.
Feature requests are welcome, but they should include sufficient detail and
explanation, as well as a discussion of perceived benefits one could expect
from them. "It would be cool if.." probably does not, in itself, constitute a
good feature request; instead, try to be specific about what you're requesting,
and what your desired feature would accomplish.
## Staying in touch
@ -181,4 +236,8 @@ Questions or other communications about contributing to Urbit can go to
[support@urbit.org][mail].
[mail]: mailto:support@urbit.org
[list]: https://groups.google.com/a/urbit.org/forum/#!forum/dev
[repo]: https://github.com/urbit/urbit
[reba]: https://www.atlassian.com/git/tutorials/merging-vs-rebasing
[issu]: https://github.com/urbit/urbit/issues
[hoon]: https://urbit.org/docs/learn/hoon/style/

16
README.md
View File

@ -64,20 +64,16 @@ git lfs pull
## Contributing
Contributions of any form are more than welcome! If something doesn't seem
right, and there is no issue about it yet, feel free to open one.
Contributions of any form are more than welcome! Please take a look at our
[contributing guidelines][cont] for details on our git practices, coding
styles, how we manage issues, and so on.
If you're looking to get involved, there are a few things you can do:
You might also be interested in:
- Join the [urbit-dev][list] mailing list.
- [Apply to Hoon School][mail], a course we run to teach the Hoon
- joining the [urbit-dev][list] mailing list.
- [applying to Hoon School][mail], a course we run to teach the Hoon
programming language and Urbit application development.
- Check out [good contributor issues][good].
Once you've got your bearings, have a look at [CONTRIBUTING.md][cont] for some
pointers on setting up your development environment.
[list]: https://groups.google.com/a/urbit.org/forum/#!forum/dev
[mail]: mailto:support@urbit.org
[good]: https://github.com/urbit/urbit/labels/good%20contributor%20issue
[cont]: https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md

58
pkg/interface/CONTRIBUTING.md Normal file
View File

@ -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 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.
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