Skip to content

Latest commit

 

History

History
104 lines (64 loc) · 4.01 KB

CONTRIBUTING.md

File metadata and controls

104 lines (64 loc) · 4.01 KB
Raw

Hacking on source-to-image

Local development

STI comes with a Makefile which defines following targets:

  • build - is the default target responsible for building STI binary, under the covers it calls hack/build-go.sh. The resulting binary will be placed in _output/local/go/bin/.
  • all - is synonym for build.
  • test - is responsible for testing STI, under the covers it calls hack/test-go.sh. Additionally you can pass WHAT or TEST variable specifying directory names to test, eg. make test WHAT=pkg/build
  • check - is synonym for test.
  • clean - cleans environment by removing _output and Godeps/_workspace/pkg directories.

Test Suites

STI uses two levels of testing - unit tests and integration tests, both of them are run on each pull request, so make sure to run those before submitting one.

Unit tests

Unit tests follow standard Go conventions and are intended to test the behavior and output of a single package in isolation. All code is expected to be easily testable with mock interfaces and stubs, and when they are not it usually means that there's a missing interface or abstraction in the code. A unit test should focus on testing that branches and error conditions are properly returned and that the interface and code flows work as described. Unit tests can depend on other packages but should not depend on other components.

The unit tests for an entire package should not take more than 0.5s to run, and if they do, are probably not really unit tests or need to be rewritten to avoid sleeps or pauses. Coverage on a unit test should be above 70% unless the units are a special case.

Run the unit tests with:

$ hack/test-go.sh

or an individual package unit test with:

$ hack/test-go.sh pkg/build/strategies/sti

To run only a certain regex of tests in a package, use:

$ hack/test-go.sh pkg/build/strategies/sti -test.run=TestLayeredBuild

To get verbose output add -v to the end:

$ hack/test-go.sh pkg/build/strategies/sti -test.run=TestLayeredBuild -v

To run all tests with verbose output:

$ hack/test-go.sh "" -v

To turn off or change the coverage mode, which is -cover -covermode=atomic by default, use:

$ STI_COVER="" hack/test-go.sh

To run tests without the go race detector, which is on by default, use:

$ STI_RACE="" hack/test-go.sh

A line coverage report is run by default when testing a single package. To create a coverage report for all packages:

$ OUTPUT_COVERAGE=true hack/test-go.sh pkg/build/strategies/sti

Integration tests

The second category are integration tests which verify the whole STI flow. The integration tests require a couple of images for testing, these can be built with hack/build-test-images.sh, if integration tests don't find them it'll print appropriate information regarding running this command.

Run the integration tests with:

$ hack/test-integration.sh

Installing Godep

STI uses Godep for dependency management. Godep allows versions of dependent packages to be locked at a specific commit by vendoring them (checking a copy of them into Godeps/_workspace/). This means that everything you need for STI is checked into this repository. To install godep locally run:

$ go get github.com/tools/godep

If you are not updating packages you should not need godep installed.

Building a Release

To build a STI release you run the hack/build-release.sh script on a system with Docker, which will create a build environment image and then execute a cross platform Go build within it. The build output will be copied to _output/releases as a set of tars containing each version.

  1. Create a new git tag git tag v0.X.X -a -m "v0.X.X" HEAD
  2. Push the tag to GitHub git push origin --tags where origin is github.com/openshift/source-to-image.git
  3. Run hack/build-release.sh
  4. Upload the binary artifacts generated by that build to GitHub release page.
  5. Send an email to the dev list, including the important changes prior to the release.