github.com/trevoraustin/hub@v2.2.0-preview1.0.20141105230840-96d8bfc654cc+incompatible/CONTRIBUTING.md (about)

     1  Contributing to hub
     2  ===================
     3  
     4  You will need:
     5  
     6  1. Go 1.3
     7  1. Ruby 1.9+
     8  2. git 1.8+
     9  3. tmux & zsh (optional) - for running shell completion tests
    10  
    11  ## What makes a good hub feature
    12  
    13  hub is a tool that wraps git to provide useful integration with GitHub. A new
    14  feature is a good idea for hub if it improves some workflow for a GitHub user.
    15  
    16  * A feature that encapsulates a git workflow *not specific* to GitHub is **not**
    17    a good fit for hub, since something like that is best implemented as an
    18    external script.
    19  * If you're proposing to add a new custom command such as `hub foo`, please
    20    research if there's a possibility that such a custom command could conflict
    21    with other commands from popular 3rd party git projects.
    22  
    23  ## How to install dependencies and run tests
    24  
    25  These instructions assume that _you already have hub installed_ and aliased as
    26  `git` (see "Aliasing").
    27  
    28  1. Clone hub:  
    29      `git clone github/hub && cd hub`
    30  1. Install necessary development dependencies:  
    31      `script/bootstrap`
    32  2. Verify that existing tests pass:  
    33      `script/test`
    34  3. Create a topic branch:  
    35      `git checkout -b feature`
    36  4. **Make your changes.**  
    37     (It helps a lot if you write tests first.)
    38  5. Verify that tests still pass:  
    39      `script/test`
    40  6. Fork hub on GitHub (adds a remote named "YOUR-USER"):  
    41      `git fork`
    42  7. Push to your fork:  
    43      `git push <YOUR-USER> HEAD`
    44  8. Open a pull request describing your changes:  
    45      `git pull-request`
    46  
    47  ## How to write tests
    48  
    49  The new test suite is written in Cucumber under `features/` directory. Each
    50  scenario is actually making real invocations to `hub` on the command-line in the
    51  context of a real (dynamically created) git repository.
    52  
    53  Whenever a scenario requires talking to the GitHub API, a fake HTTP server is
    54  spun locally to replace the real GitHub API. This is done so that the test suite
    55  runs faster and is available offline as well. The fake API server is defined
    56  as a Sinatra app inline in each scenario:
    57  
    58  ```
    59  Given the GitHub API server:
    60    """
    61    post('/repos/github/hub/pulls') {
    62      status 200
    63    }
    64    """
    65  ```
    66  
    67  The best way to learn to write new tests is to study the existing scenarios for
    68  commands that are similar to those that you want to add or change.