|
| 1 | +# Contribution Guide |
| 2 | + |
| 3 | +The `softlayer_api` Ruby Gem is an open source project and the developers who use it have an opportunity to tailor its direction. Here are some guideposts to help contributors get started with the code and ensure that their additions fit into the structure and style of the Gem. If you are new to the project, we hope this will help you along the way, if you find something is missing, however, please open an issue in GitHub against the documentation; or, since the documentation itself is part of the open source project, please feel free to submit changes to this guide which might leave some footprints those who follow along behind you. |
| 4 | + |
| 5 | +# Requesting Changes |
| 6 | + |
| 7 | +Any requests for enhancements, new features, or bug reports should be entered into the softlayer-ruby GitHub repository as "[issues](https://github.com/softlayer/softlayer-ruby/issues?state=open)". |
| 8 | + |
| 9 | +# Development Environment |
| 10 | + |
| 11 | +As a Ruby project, your first step will be to install the [Ruby Programming Language](https://www.ruby-lang.org/en/). Many Unix-derived environments, including Mac OS X, have a version or Ruby installed by default, however, the default version may be out-of-date. Please visit the main Ruby language [site](https://www.ruby-lang.org/en/) for instructions on installing an up-to-date build of Ruby for your computing environment. |
| 12 | + |
| 13 | +The Gem supports multiple versions of Ruby, and we recommend using Ruby 2.0 or later. The [Ruby Version Manager (rvm)](https://rvm.io) is an invaluable tool to help keep track of multiple versions of Ruby. The Gem no longer supports Ruby 1.8.7. Support for Ruby 1.9 will continue for a time, but the Core Ruby team is already withdrawing their support for that version. |
| 14 | + |
| 15 | +Source code management is handled through [Git](http://git-scm.com), and GitHub hosts the primary repository, [Softlayer-Ruby](https://github.com/softlayer/softlayer-ruby). GitHub also handles bug tracking and feature suggestions through issues. |
| 16 | + |
| 17 | +The `softlayer_api` gem is a pure Ruby project. There are, at the time of this writing, no native libraries built into the gem so no native C or C++ tools should be necessary. If you prefer to use a Ruby IDE, any of them should work, as should a simple text editor such as [vim](http://www.vim.org), [emacs](http://www.gnu.org/software/emacs/), [Sublime](http://www.sublimetext.com) or [TextMate](http://macromates.com). |
| 18 | + |
| 19 | +Source code documentation is built using [Rdoc](https://github.com/rdoc/rdoc) |
| 20 | + |
| 21 | +Unit testing is handled through [RSpec](http://rspec.info) and we prefer specs to *try* to follow the guidelines found at [betterspecs.org](http://betterspecs.org). |
| 22 | + |
| 23 | +Building and makefile functionality is handled by [Rake](https://github.com/jimweirich/rake). |
| 24 | + |
| 25 | +Configuration and dependency management is accomplished using [Bundler](http://bundler.io) |
| 26 | + |
| 27 | +When changes are submitted to GitHub, the [Travis CI](https://travis-ci.org) continuous integration platform runs the unit tests as a means of smoke testing submitted code. |
| 28 | + |
| 29 | +# Setting up |
| 30 | + |
| 31 | +To set up a development environment you should have Ruby installed and select an editor. Fork the [Softlayer-Ruby](https://github.com/softlayer/softlayer-ruby) project in GitHub, and clone your fork to your local machine. Change into the root directory, and if necessary, use the Ruby Gems command line tools to install bundler: |
| 32 | + |
| 33 | + $ gem install bundler |
| 34 | + |
| 35 | +To ask Bundler to install all the other gems required to work with the `softlayer_api` gem, issue the command: |
| 36 | + |
| 37 | + $ bundler install |
| 38 | + |
| 39 | +At this point you should be able to run all the unit tests for the gem. Running the unit tests is as easy as invoking rake with the default build action: |
| 40 | + |
| 41 | + $ rake |
| 42 | + |
| 43 | +Once the unit tests are finished you should see a completion message that looks something like: |
| 44 | + |
| 45 | + Finished in 1.19 seconds (files took 0.50089 seconds to load) |
| 46 | + 252 examples, 0 failures |
| 47 | + |
| 48 | +(The actual number of examples run will probably vary) |
| 49 | + |
| 50 | +# Building the Gem |
| 51 | + |
| 52 | +To build the gem, you ask rake to do the heavy lifting: |
| 53 | + |
| 54 | + $ rake build |
| 55 | + |
| 56 | +gems are built into the `pkg` directory and will have a name of the form `softlayer_api-<version>.gem.` where `<version>` will be the version of the `softlayer_api` gem. |
| 57 | + |
| 58 | +You can install your modified gem to your system with the gem command: |
| 59 | + |
| 60 | + $ bundle gem install pkg/softlayer_api-<version>.gem |
| 61 | + |
| 62 | +(don't forget to substitute the version you are installing where the `<version>` tag appears in the command line above) |
| 63 | + |
| 64 | +# Running the Tests |
| 65 | + |
| 66 | +The unit tests in the Gem are written using [RSpec](http://rspec.info). They are also integrated into the `rake` build system and the default action is to run the tests. As a result, from the root source directory, any of the following commands will run the unit tests: |
| 67 | + |
| 68 | + $ rspec |
| 69 | + $ rake spec |
| 70 | + $ rake |
| 71 | + |
| 72 | +Coverage of the unit tests is not 100%, but we heartily recommend that you add unit tests for any new code you add to the gem. |
| 73 | + |
| 74 | +# Building documentation |
| 75 | + |
| 76 | +To build documentation for the gem, use the `rdoc` or `rerdoc` actions with the `rake` command: |
| 77 | + |
| 78 | + $ rake rdoc |
| 79 | + $ rake rerdoc |
| 80 | + |
| 81 | +documentation is built in the `doc` folder and the main file is `doc/index.html` |
| 82 | + |
| 83 | +API documentation is written inline within the source using RDoc. Supplementary documentation is found in the doc_src folder and is primarily written in [markdown](http://daringfireball.net/projects/markdown/syntax). |
| 84 | + |
| 85 | +# Directory Structure |
| 86 | + |
| 87 | +The basic directory structure for the source tree is as follows |
| 88 | + |
| 89 | + doc # Built by RDoc when documentation is generated |
| 90 | + doc_src # Static pages (in markdown format) that are included with the documentation. You're reading one now. |
| 91 | + examples # Sample scripts offering examples of using the softlayer_api gem |
| 92 | + lib # Container for the source code of the gem |
| 93 | + softlayer # Folder containing most of the gem's actual source code |
| 94 | + log # RVM will create a log folder when running commands across multiple ruby versions. |
| 95 | + pkg # Created when the gem is built, contains built versions of the gem |
| 96 | + spec # Source directory for the RSpec testing specifications |
| 97 | + fixtures # Files used by the unit tests to mock responses from the SoftLayer network API |
| 98 | + |
| 99 | +Most of the source files that implement the gem are found in `lib/softlayer`. If you wish to add new functionality, or edit existing functionality, you will probably edit the class files in this directory. Unit tests using Rspec are found in the spec folder and should generally follow the naming convention of <Class>_spec.rb |
| 100 | + |
| 101 | +Although there are exceptions, most of the source code follows the convention of having a single source file per class, and the file is named after the class it contains. |
| 102 | + |
| 103 | +# Style |
| 104 | + |
| 105 | +Questions of coding style are the source of massive levels of angst and unrest in development communities. We ask contributors to be tolerant in what they will accept, and liberal in their personal style. We ask contributors to review the [ruby style guide](https://github.com/styleguide/ruby) available on GitHub. In particular we prefer that contributors follow the suggestions: |
| 106 | + |
| 107 | +* Use soft-tabs with a two space indent. |
| 108 | +* Keep lines fewer than 80 characters (more or less). |
| 109 | +* Never leave trailing whitespace. |
| 110 | +* End each file with a blank newline. |
| 111 | + |
| 112 | +Commits to the project to remove whitespace have been made, although we prefer them as stand-alone commits with appropriate commenting. |
| 113 | + |
| 114 | +Contrary to the style guide, we use Rdoc for documentation not TomDoc. |
| 115 | + |
| 116 | +We strongly recommend that the naming guidelines in the style guide be followed. Ruby language variables and methods should be named using `snake_case`. This is particularly valuable since the SoftLayer network API uses `camelCase` as its naming convention and having the two styles helps to indicate which environment a method name or identifier comes from. |
| 117 | + |
| 118 | +The Gem uses an exclamation mark (!) to mark methods that have strong consequences to the SoftLayer Environment. This includes methods that delete, destroy, or otherwise permanently modify an entity in the environment, or requests that might cause additional charges to be applied to a customer account. For example, the method for permanently canceling a server is `cancel!` and the method for placing an order (and incurring additional charges to the account) is `place_order!`. |
| 119 | + |
| 120 | +# Model Layer Changes |
| 121 | + |
| 122 | +The Model Layer of the `softlayer_api` gem is intended to allow scripts to access information easily and make common modifications to a SoftLayer environment with straightforward code. As such, it is important that the model itself be sound. For contributors who wish to add new models to this layer, we recommend that you present your design in an issue on GitHub and solicit the constructive advice of the community on your model. In particular we recommend the following for consideration on good model design: |
| 123 | + |
| 124 | +* [SOLID object oriented design](http://en.m.wikipedia.org/wiki/SOLID_(object-oriented_design)) |
| 125 | +* [The DRY principle](http://en.wikipedia.org/wiki/Don't_repeat_yourself) |
| 126 | + |
| 127 | +These are guidelines, not rules, and model design is as subject to opinion and subjectivity as other programming topics. |
| 128 | + |
| 129 | +If you intend to offer new models, please carefully review the Model Layer documentation in this set as subclasses of ModelBase are expected to conform to particular protocols. |
| 130 | + |
| 131 | +# Submitting Changes |
| 132 | + |
| 133 | +Contributions are made to the `softlayer_api` Gem by submitting a pull-request on GitHub. The community will review pull requests and offer constructive advice on improvements. The determination on whether a pull-request will be accepted into the gem is made at the sole discretion of SoftLayer with the wise counsel of the community. |
| 134 | + |
0 commit comments