Skip to content

Latest commit

 

History

History
175 lines (125 loc) · 7.13 KB

CONTRIBUTING.md

File metadata and controls

175 lines (125 loc) · 7.13 KB
Raw

Getting Involved

New contributors are always welcome, and when in doubt please ask questions! We strive to be an open and welcoming community. Please be nice to one another.

We recommend heading over to fog's CONTRIBUTING and having a look around as well. It has information and context about the state of the fog project as a whole.

Coding

  • Pick a task:
  • Fork the project, add your changes and tests to cover them in a topic branch.
    • Fork
    • Create your feature branch (git checkout -b my-new-feature)
    • Commit your changes (git commit -am 'Add some feature')
    • Push to the branch (git push origin my-new-feature)
    • Create a new pull request
  • Commit your changes and rebase against fog/fog-google to ensure everything is up to date.
  • Submit a pull request

Non-Coding

  • Offer feedback or triage open issues.
  • Improve documentation. See project's inch tracker for ideas for where to get started.
  • Organize or volunteer at events.

Contributing Code

This document is very much a work in progress. Sorry about that.

It's worth noting that, if you're looking through the code, and you'd like to know the history of a line, you may not find it in the history of this repository, since most of the code was extracted from fog/fog. So, you can look at the history from commit fog/fog#c596e backward for more information.

Development environment

If you're going to be doing any kind of modifications, we highly recommend using rbenv, ruby-build, (don't forget the dependencies!) and bundler.

Once you've got that all installed, run

$ bundle install

to install the required gems. You might have to fight a bit to get Nokogiri installed.

Then, you should be ready to go! If you'd like to drop into an interactive shell, configured with your :default credential, use

$ rake console

Documentation

Code should be documented using YARDoc syntax. We use inch to keep track of overall doc coverage and inch-ci to keep track of changes over time.

You can view a doc coverage report by running:

$ inch

Or view suggestions on a specific method:

$ inch show Fog::Compute::Google::Server#set_metadata

Testing

This module is tested with Minitest.

Integration tests

Live integration tests can be found in test/integration/.

Most of the library functionality is currently covered with them. To simplify things for contributors we have a CI system that runs all integration tests in parallel against all pull requests marked with integrate label that anyone in fog-google team can set. Read CI section for more info.

After completing the installation in the README, (including setting up your credentials and keys,) make sure you have a :test credential in ~/.fog, something like:

test:
  google_project: my-project
  google_json_key_location: /path/to/my-project-xxxxxxxxxxxxx.json

Then you can run all the live tests:

$ bundle exec rake test

or just one API:

$ bundle exec rake test:compute

(See rake -T for all available tasks)

or just one test:

$ bundle exec rake test TESTOPTS="--name=TestServers#test_bootstrap_ssh_destroy"

or a series of tests by name:

$ bundle exec rake test TESTOPTS="--name=/test_nil_get/"

Unit tests

Some basic sanity checking and logic verification is done via unit tests located in test/unit. They automatically run against every pull request via Travis CI.

You can run unit tests like so:

$ rake test:unit

We're in progress of extending the library with more unit tests and contributions along that front are very welcome.

The transition from shindo to Minitest

Previously, shindo was the primary testing framework. We've moved away from it, and to Minitest, but some artifacts may remain.

For more information on transition, read #50.

Continuous integration

Currently Google maintains a Concourse CI server, running a pipeline defined in ci folder. It automatically runs all integration tests against every pull-request marked with integration label.

For more information on the pipeline please refer to the ci README.

Some notes about the tests as they stand

The live integration tests for resources, (servers, disks, etc.,) have a few components:

  • The TestCollection mixin module lives in test/helpers/test_collection.rb and contains the standard tests to run for all resources, (e.g. test_lifecycle). It also calls cleanup on the resource's factory during teardown, to make sure that resources are getting destroyed before the next test run.
  • The factory, (e.g. ServersFactory, in test/integration/factories/servers_factory.rb,) automates the creation of resources and/or supplies parameters for explicit creation of resources. For example, ServersFactory initializes a DisksFactory to supply disks in order to create servers, and implements the params method so that tests can create servers with unique names, correct zones and machine types, and automatically-created disks. ServersFactory inherits the create method from CollectionFactory, which allows tests to create servers on-demand.
  • The main test, (e.g. TestServers, in test/integration/compute/test_servers.rb,) is the test that actually runs. It mixes in the TestCollection module in order to run the tests in that module, it supplies the setup method in which it initializes a ServersFactory, and it includes any other tests specific to this collection, (e.g. test_bootstrap_ssh_destroy).

If you want to create another resource, you should add live integration tests; all you need to do is create a factory in test/integration/factories/my_resource_factory.rb and a main test in test/integration/compute/test_my_resource.rb that mixes in TestCollection.