gopkg.in/openshift/source-to-image.v1@v1.2.0/CONTRIBUTING.md (about)

     1  Hacking on source-to-image
     2  ==========================
     3  
     4  ## Local development
     5  
     6  S2I comes with a `Makefile` which defines following targets:
     7  
     8  * `build` - is the default target responsible for building S2I binary, under the covers
     9  it calls `hack/build-go.sh`. The resulting binary will be placed in `_output/local/go/bin/`.
    10  * `all` - is synonym for `build`.
    11  * `test` - is responsible for testing S2I, under the covers it calls `hack/test-go.sh`.
    12  Additionally you can pass `WHAT` or `TEST` variable specifying directory names to test,
    13  eg. `make test WHAT=pkg/build`
    14  * `check` - is synonym for `test`.
    15  * `clean` - cleans environment by removing `_output`
    16  
    17  ## Generating Bash completion
    18  
    19  If you are modifying or adding sub-command or command flag, make sure you update
    20  the generated Bash completion and include it in your PR. To update Bash
    21  completion, you can run the following command:
    22  
    23      $ hack/update-generated-completions.sh
    24  
    25  This will regenerate the `./contrib/bash/s2i` file.
    26  
    27  ## Test Suites
    28  
    29  S2I uses two levels of testing - unit tests and integration tests, both of them are run on each
    30  pull request, so make sure to run those before submitting one.
    31  
    32  
    33  ### Unit tests
    34  
    35  Unit tests follow standard Go conventions and are intended to test the behavior and output of a
    36  single package in isolation. All code is expected to be easily testable with mock interfaces and
    37  stubs, and when they are not it usually means that there's a missing interface or abstraction in the
    38  code. A unit test should focus on testing that branches and error conditions are properly returned
    39  and that the interface and code flows work as described. Unit tests can depend on other packages but
    40  should not depend on other components.
    41  
    42  The unit tests for an entire package should not take more than 0.5s to run, and if they do, are
    43  probably not really unit tests or need to be rewritten to avoid sleeps or pauses. Coverage on a unit
    44  test should be above 70% unless the units are a special case.
    45  
    46  Run the unit tests with:
    47  
    48      $ hack/test-go.sh
    49  
    50  or an individual package unit test with:
    51  
    52      $ hack/test-go.sh pkg/build/strategies/sti
    53  
    54  To run only a certain regex of tests in a package, use:
    55  
    56      $ hack/test-go.sh pkg/build/strategies/sti -test.run=TestLayeredBuild
    57  
    58  To get verbose output add `-v` to the end:
    59  
    60      $ hack/test-go.sh pkg/build/strategies/sti -test.run=TestLayeredBuild -v
    61  
    62  To run all tests with verbose output:
    63  
    64      $ hack/test-go.sh "" -v
    65  
    66  To run tests without the Go race detector, which is on by default, use:
    67  
    68      $ S2I_RACE="" hack/test-go.sh
    69  
    70  A line coverage report is printed by default. To turn it off, use:
    71  
    72      $ S2I_COVER="" hack/test-go.sh
    73  
    74  To create an HTML coverage report for all packages:
    75  
    76      $ OUTPUT_COVERAGE=/tmp/s2i-cover hack/test-go.sh
    77  
    78  
    79  ### Integration tests
    80  
    81  The second category are integration tests which verify the whole S2I flow. The integration tests
    82  require a couple of images for testing, these can be built with `hack/build-test-images.sh`, if
    83  integration tests don't find them it'll print appropriate information regarding running this command.
    84  
    85  Run the integration tests with:
    86  
    87      $ hack/test-integration.sh
    88  
    89  
    90  ## Installing Glide
    91  
    92  S2I uses [Glide](https://github.com/Masterminds/glide) for dependency management.
    93  Glide allows versions of dependent packages to be locked at a specific commit by *vendoring* them
    94  (checking a copy of them into `vendor`).  This means that everything you need for
    95  S2I is checked into this repository.  To install `glide` locally run:
    96  
    97      $ go get github.com/Masterminds/glide
    98  
    99  If you are not updating packages you should not need glide installed.
   100  
   101  
   102  ## Building a Release
   103  
   104  To build a S2I release you run `make release` on a system with Docker,
   105  which will create a build environment image and then execute a cross platform Go build within it. The build
   106  output will be copied to `_output/releases` as a set of tars containing each version.
   107  
   108  1. Create a new git tag `git tag vX.X.X -a -m "vX.X.X" HEAD`
   109  2. Push the tag to GitHub `git push origin --tags` where `origin` is `github.com/openshift/source-to-image.git`
   110  4. Run `make release`
   111  5. Upload the binary artifacts generated by that build to GitHub release page.
   112  6. Send an email to the dev list, including the important changes prior to the release.