mirror of
https://github.com/ilyakooo0/urbit.git
synced 2024-09-11 10:46:43 +03:00
contributing: add git/release info
Revamps the "Git practice" section to make it less of a git and GitHub tutorial and more of a guide of expected contribution style. In particular, it answers the questions of: * what tree contributors should branch from * how to submit contributions * how to structure commits * how to format commit descriptions * what contributions are considered acceptable * what our expectations are around committing pills Additionally, adds a "Releases" section that describes how we go about making and deploying releases.
This commit is contained in:
parent
052903a4ee
commit
2132f13d29
129
CONTRIBUTING.md
129
CONTRIBUTING.md
@ -35,54 +35,101 @@ $ 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 (<= 50 characters total)
|
||||
>
|
||||
> long description (optional)
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Next, start a new branch to do your work on. Normally you'll want to use the
|
||||
`master` branch as your starting point:
|
||||
|
||||
```
|
||||
$ 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
|
||||
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.
|
||||
|
||||
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
|
||||
@ -181,4 +228,6 @@ 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
|
||||
|
Loading…
Reference in New Issue
Block a user