Skip to content

Latest commit

 

History

History
101 lines (79 loc) · 3.6 KB

CONTRIBUTING.md

File metadata and controls

101 lines (79 loc) · 3.6 KB
Raw

Contributing to hub

Warning: in the near future, hub might be implemented entirely in Go instead of Ruby. Keep that in mind, and don't contribute big features/refactorings to the Ruby codebase, as such pull requests will be unlikely to get accepted.

You will need:

  1. Ruby 1.8.7+
  2. git 1.8+
  3. tmux & zsh (optional) - for running shell completion tests

What makes a good hub feature

hub is a tool that wraps git to provide useful integration with GitHub. A new feature is a good idea for hub only if it relates to both git and GitHub.

  • A feature that adds GitHub Issues management is not a good fit for hub since it's not git-related. Please use ghi instead.
  • 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

These instructions assume that you already have hub installed and aliased as git (see "Aliasing").

  1. Clone hub:
    git clone github/hub && cd hub
  2. Ensure Bundler is installed:
    which bundle || gem install bundler
  3. Install development dependencies:
    bundle install
  4. Verify that existing tests pass:
    script/test
  5. Create a topic branch:
    git checkout -b feature
  6. Make your changes.
    (It helps a lot if you write tests first.)
  7. Verify that tests still pass:
    script/test
  8. Fork hub on GitHub (adds a remote named "YOUR-USER"):
    git fork
  9. Push to your fork:
    git push <YOUR-USER> HEAD
  10. Open a pull request describing your changes:
    git pull-request

How hub works

  1. Runner handles the command-line invocation;

  2. Args wraps ARGV for easy access;

  3. Commands dispatches each command to the appropriate method, e.g. hub pull-request runs the pull_request method. Each method processes args as needed, using Context and GitHubAPI in the process;

  4. Context handles inspecting the current environment and git repository;

  5. GitHubAPI handles GitHub API authentication and communication;

  6. And finally, Runner receives the resulting arguments to execute in the shell by forwarding them to git.

How to write tests

The old test suite for hub was written in test/unit and some legacy tests can still be found in the test/ directory. Unless you have a need for writing super-isolated unit tests, do not add any more tests to this suite.

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.