ilyakooo0/urbit
1
0
Fork 0
mirror of https://github.com/ilyakooo0/urbit.git synced 2024-08-15 13:40:31 +03:00
Code Issues Packages Projects Releases Wiki Activity

contributing: add git/release info

Browse Source 
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:
Jared Tobin 2019-08-28 12:02:44 -02:30
parent 052903a4ee
commit 2132f13d29
No known key found for this signature in database
GPG Key ID: 0E4647D58F8A69E4
1 changed files with 89 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
CONTRIBUTING.md
View File

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