CONTRIBUTING.md

How to contribute

Git Town is a welcoming community, and we'd love for everyone to bring their contributions of any size to make it even better.

• Found a bug or have an idea for a new feature? - Open an issue
• Fixed a bug or created a new feature that others will enjoy? - Create a pull request

This guide will help you get started and outline some things you should know when developing Git Town.

Setup

• install Go version 1.9 or higher
  • on macOS via brew install go
  • on Windows via the official Go installer
• install Ruby 2.4.1 to run the feature tests
  • prefer install with rbenv
  • run gem install bundler
• install Yarn
• set up the Go directory structure on your machine
  • set the environment variable $GOPATH to your Go workspace (you can point it to any folder on your hard drive, let's assume ~/go here)
  • add ~/go/bin to your $PATH
  • create the directory ~/go/src/github.com/Originate
  • cd into that directory, and run git clone git@github.com:Originate/git-town.git
  • cd into $GOPATH/src/github.com/Originate/git-town
• make sure you have make - Mac and Linux users should be okay, Windows users should install Make for Windows
• run make setup and then make build
• now you can run git-town on the command line
• see https://golang.org/doc/install#testing for details on how to test
• optionally install Tertestrial for auto-running tests

Building

• run make build to compile the source code into a runnable binary in $GOPATH/bin

Testing

• tests are written in Cucumber and RSpec.
• all features need to have comprehensive test coverage
• source code and test files must pass the linters
• See here for how to run the tests

In the Go-based Cucumber setup, a GitManager manages the setup of the Git repositories for testing Git Town. For each scenario, GitManager provides a standardized GitEnvironment that looks like this:

• The "developer" GitRepository contains the local workspace repo. This is where the feature specs run.
• The "origin" GitRepository contains the remote repo for the workspace repo in the "developer" folder. This is where pushes from "developer" go to.
• All repos are preconfigured:
  • there exists a "main" branch
  • this branch is configured as Git Town's main branch.

Setting up a GitEnvironment takes a while because it requires several Git operations, and it has to be done for every scenario run. As a performance optimization, the GitManager creates a "memoized" environment, i.e. a cache of an entirely set up GitEnvironment and makes copies of it for scenarios.

When running Go-based Cucumber concurrently, it creates only one global GitManager instance that is shared by all threads.

Developing

• all dependencies are located in the vendor folder, which is checked into Git
• update dependencies: make update
• adding a new Go library:
  • run dep ensure --add <package name>
  • start using it in the code
  • your pull request for the feature that requires the new library should contain the updated Gopkg.* files and vendor folder

Command documentation

Every Git Town command

• has a Markdown page that is identical to the man page
• is listed on the README

Achitecture documents

• architecture overview
• branch hierarchy - how Git Town sees branches
• drivers - third-party specific functionality
• steps list - the architecture behind most of the Git Town commands

Website development

• See here

Code style

Please follow the existing code style.

Pull Requests

Each pull request (PR) should have the same (optional) description that it will have when committed later and include the issue it resolves.

When merging approved PRs:

• use git town ship
• the message for the squashed commit should follow the formatting guidelines for commit messages
• mention the closed issue in the commit body, so that the respective issue is automatically closed.

Example of a commit message:

Automatically foo commits in "git bar"

Fooing changes before they get barred into a separate branch
keeps the final foo simpler when shipping that branch later.

Implements #123

Release Process

Originate/git-town

• Create a feature branch which updates RELEASE_NOTES.md
• Get the feature branch reviewed and merged
• Create and push a new Git Tag for the release
  • git tag -m release -a v4.0
  • git push --tags
• Travis-CI creates a new release on GitHub and attaches the GT binaries to it

Homebrew/homebrew

• Fork Homebrew
• Update Library/Formula/git-town.rb
  • Get the sha256 by downloading the release (.tar.gz) and using shasum -a 256 /path/to/file
  • Ignore the bottle block. It is updated by the homebrew maintainers
• Create a pull request and get it merged