From 2132f13d29d6f1b308299fb11d17b7040a4b3a8f Mon Sep 17 00:00:00 2001 From: Jared Tobin Date: Wed, 28 Aug 2019 12:02:44 -0230 Subject: [PATCH] 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. --- CONTRIBUTING.md | 129 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 89 insertions(+), 40 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6bf3a0f15..99a30893a 100644 --- a/CONTRIBUTING.md +++ b/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