CONTRIBUTING.md

Contributing to oshinko-rest

The oshinko-rest application is a Go language based REST server that is defined by an OpenAPI (fka Swagger) file in api/swagger.yaml. From this file, the framework of the REST application is generated by using the go-swagger toolkit.

Adding new source code

When adding to the source base for oshinko-rest, it is important not to add code in the auto-generated portions as it may be overwritten by future regenerations. To this end, there are several locations which should be avoided for new code:

• client directory
• cmd/oshinko-rest-server/main.go
• models directory
• restapi directory, aside from the file restapi/configure_oshinko_rest.go

These directories should be avoided when adding new source code. The main point of contact for interacting with the server, and its internal resources, is the file restapi/configure_oshinko_rest.go. This file will not be touched by successive regenerations of the go-swagger based code. This file also contains several entry point functions for interacting with the server.

Dependencies

This project is using the vendor experiment that was merged in Go language version 1.5[1][2]. As such, all dependencies required by oshinko-rest should be stored in the vendor directory at the top of the project oshinko-cli (../vendor), they should not be included through the standard $GOPATH mechanism.

The files under the vendor directory should be structured as if they were under the $GOPATH/src directory for a Go language installation, with the exeception that we should not commit git repositories. If your new code requires an external dependency, it should be added to the vendor directory with its fully qualified path as seen in an import statement.

For example, if I wish to add source code that requires me to import github.com/foo/bar, then I should copy the contents of that repository to the directory ../vendor/github.com/foo/bar in this project.

In this manner, we can ensure that the dependency chain for the oshinko-rest application will be frozen around the sources that are contained in the vendor directory.

Godeps

To improve the provenance of the dependencies that are carried within the vendor directory, the Godeps/Godeps.json has been added to record the individual packages and commit hashes for each dependency. This file is usually generated by the godep tool, but as this project contains dependencies on the OpenShift Origin project(which carries its own modified dependencies), the GoDeps.json file has been created in a custom manner.

The dependencies for this project have been seeded by first copying the vendor directory from the upstream OpenShift Origin project (https://github.com/openshift/origin), the Godeps directory is also copied. After the initial copy, the Origin project itself is copied into the vendor and its vendor, Godeps and .git directories are removed. Finally, as the rest server code contains a few extra dependencies, those are added manually by copying them from github into the appropriate locations in the vendor directory and their entries added to the Godeps.json file.

Dependency creation steps

1. copy vendor directory from openshift/origin to root of oshinko-cli
2. copy Godeps directory from openshift/origin to root of oshinko-cli
3. copy openshift/origin to ./vendor/github.com/openshift/
4. remove vendor, Godeps and .git directories from the copied ./vendor/github.com/openshift/origin/ directory
5. add rest dependencies to vendor directory and Godeps.json file

Note on REST server dependencies As of the v0.2.2 release of the oshinko-cli package, the REST server has the following dependencies above and beyond the dependencies for core and cli:

1. github.com/jessevdk/go-flags
2. github.com/rs/cors
3. github.com/rs/xhandler
4. github.com/tylerb/graceful

Unit tests

All code that is contributed to this project should include unit tests that exercise its functionality. Exceptions to this rule can be made in cases where the underlying functions rely on difficult to configure resources or the code is simple enough as to not have multiple execution paths.

The unit tests reside in the tests/unit directory, and are namespaced in the unittest package. The gocheck framework is being used to structure these tests. To examine the suite structure or test runner hooks see the tests/unit/configure_test.go file.

New tests should be added to files in the tests/unit directory, and should be named in the pattern of <topic>_test.go. Any function that matches the type and name of func (*OshinkoUnitTestSuite) TestXxx (*check.C) will be executed.

The OshinkoUnitTestSuite structure can be found in the tests/unit/configure_test.go file. It can be modified with information that may need to be passed in to a test, or state that must be maintained between tests. This file also contains several functions that can be used for setting up and tearing down test or suites.

To run these tests use the test target in the Makefile.

Example unit test

This example shows a simple test being added to a file named tests/unit/example_test.go.

package unittest

import (
	"gopkg.in/check.v1"
)

func (s *OshinkoUnitTestSuite) TestExample(c *check.C) {
    c.Assert(true, check.Equals, true)
}

Client tests

A suite of client tests exists in the tests/client directory. These tests make use of the gocheck framework that is used for the unit tests. They work by instantiating a server and issuing client commands against that server.

To write new client tests, it is strongly advised to investigate the configuration code in tests/client/configure_test.go, and the TestCreateAndDeleteCluster test in the tests/client/clusters_client_test.go file. There are several features, such as access to the server object, which are created as members of the OshinkoRestTestSuite which will be helpful for test developers.

To run the client tests, the tools/oshinko-test.sh is provided to assist with the OpenShift interactions. This script requires that you have access to the oc command and that you are authenticated as a user with permissions to perform all the admin functions required. Please inspect this script for more details.

Note the client test script is not idempotent, it is meant to be run in a project once. If it is re-rerun in the same project, it will fail with errors about objects already existing. A new project should be used for each run of the client test suite.