CONTRIBUTING.md 2.5 KB
Newer Older
1 2 3
Contributing to hub
===================

4 5 6
This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to uphold this code.
[code-of-conduct]: http://todogroup.org/opencodeofconduct/#Hub/opensource@github.com

7 8
You will need:

M
Mislav Marohnić 已提交
9 10
1. Go 1.6+
1. Ruby 1.9+ with Bundler
11 12 13
2. git 1.8+
3. tmux & zsh (optional) - for running shell completion tests

M
Mislav Marohnić 已提交
14 15 16 17
We will also require you to sign the [GitHub Contributor License Agreement](https://cla.github.com/)
after you submit your first pull request to this project. The link to sign the
agreement will be presented to you in the web interface of the pull request.

18 19 20
## What makes a good hub feature

hub is a tool that wraps git to provide useful integration with GitHub. A new
21
feature is a good idea for hub if it improves some workflow for a GitHub user.
22 23 24 25 26 27 28 29 30 31

* A feature that encapsulates a git workflow *not specific* to GitHub is **not**
  a good fit for hub, since something like that is best implemented as an
  external script.
* If you're proposing to add a new custom command such as `hub foo`, please
  research if there's a possibility that such a custom command could conflict
  with other commands from popular 3rd party git projects.

## How to install dependencies and run tests

J
Jingwen Owen Ou 已提交
32
1. Clone hub:
M
Mislav Marohnić 已提交
33
    `git clone https://github.com/github/hub.git && cd hub`
J
Jingwen Owen Ou 已提交
34
2. Verify that existing tests pass:
M
Mislav Marohnić 已提交
35
    `make test-all`
J
Jingwen Owen Ou 已提交
36
3. Create a topic branch:
37
    `git checkout -b feature`
J
Jingwen Owen Ou 已提交
38
4. **Make your changes.**
39
   (It helps a lot if you write tests first.)
M
Mislav Marohnić 已提交
40
5. Verify that the tests still pass.
J
Jingwen Owen Ou 已提交
41
6. Fork hub on GitHub (adds a remote named "YOUR-USER"):
M
Mislav Marohnić 已提交
42
    `make && bin/hub fork`
J
Jingwen Owen Ou 已提交
43
7. Push to your fork:
M
Mislav Marohnić 已提交
44
    `git push -u <YOUR-USER> HEAD`
J
Jingwen Owen Ou 已提交
45
8. Open a pull request describing your changes:
M
Mislav Marohnić 已提交
46
    `bin/hub pull-request`
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69

## How to write tests

The new test suite is written in Cucumber under `features/` directory. Each
scenario is actually making real invocations to `hub` on the command-line in the
context of a real (dynamically created) git repository.

Whenever a scenario requires talking to the GitHub API, a fake HTTP server is
spun locally to replace the real GitHub API. This is done so that the test suite
runs faster and is available offline as well. The fake API server is defined
as a Sinatra app inline in each scenario:

```
Given the GitHub API server:
  """
  post('/repos/github/hub/pulls') {
    status 200
  }
  """
```

The best way to learn to write new tests is to study the existing scenarios for
commands that are similar to those that you want to add or change.