Skip to content

Commit efb3fbf

Browse files
SLsthompsonSLsthompson
committed
Fleshed out the contribution guide and ran everything through a round of spell checking
1 parent 08ad609 commit efb3fbf

3 files changed

Lines changed: 136 additions & 3 deletions

File tree

‎doc_src/Contribution Guide.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,134 @@
11
# 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+

‎doc_src/Model Layer.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# `softlayer_api` Model Layer
22

3-
The Model Layer builds upon the Foundation layer and offers abstractions of the entities in the SoftLayer enviornment. For example, computing assets in the SoftLayer environment are found in two separate services [SoftLayer_Hardware](http://sldn.softlayer.com/reference/services/SoftLayer_Hardware) and [SoftLayer_Virtual_Guest](http://sldn.softlayer.com/reference/services/SoftLayer_Virtual_Guest). The Model Layer, however, creates a Server abstraction on top of those services. By doing so, a Ruby script can work with an instance of the SoftLayer::Server object class, send that object the "cancel!" message, and trust the underlying object framework to route the message to the appropriate service and routine within the network API.
3+
The Model Layer builds upon the Foundation layer and offers abstractions of the entities in the SoftLayer environment. For example, computing assets in the SoftLayer environment are found in two separate services [SoftLayer_Hardware](http://sldn.softlayer.com/reference/services/SoftLayer_Hardware) and [SoftLayer_Virtual_Guest](http://sldn.softlayer.com/reference/services/SoftLayer_Virtual_Guest). The Model Layer, however, creates a Server abstraction on top of those services. By doing so, a Ruby script can work with an instance of the SoftLayer::Server object class, send that object the "cancel!" message, and trust the underlying object framework to route the message to the appropriate service and routine within the network API.
44

55
The Model Layer is not meant to be complete. In fact, it models just a few key elements of the SoftLayer environment at this point, however we hope the Model Layer will grow and encompass more of the entities found in the API over time. In the interim, however, the current framework includes some convenient bridges that allow Ruby scripts to move from working with the abstractions of the Model Layer to the lower-level routines of the Foundation API easily.
66

7-
The details of the individual classes that for the object class hierarchy of the Model layer are included in the API documentaiton. This document will discuss some of the general features of the Model Layer and the bridges that are in place to help code move between the Foundation and Model Layers.
7+
The details of the individual classes that for the object class hierarchy of the Model layer are included in the API documentation. This document will discuss some of the general features of the Model Layer and the bridges that are in place to help code move between the Foundation and Model Layers.
88

99
# The ModelBase Class
1010

‎doc_src/Welcome.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ The `softlyer_api` Ruby Gem provides a convenient way to call into the SoftLayer
44

55
For more information about the SoftLayer API, and the routines and data structures it offers should visit the [SoftLayer Developer Network (SLDN) website](http://sldn.softlayer.com).
66

7-
This document is written for Ruby developers who wish to interact with their SoftLayer accounts through Ruby scripts. SoftLayer also offers a command line tool for performing common tasks. If prefer to use that tool, we invite you to look into the [command line interface](https://softlayer-python.readthedocs.org/en/latest/cli.html) that is part of the [softlayer-python](http://github.com/softlayer/softlayer-python) project.
7+
This document is written for Ruby developers who wish to interact with their SoftLayer accounts through Ruby scripts. SoftLayer also offers a command line tool for performing common tasks. If prefer to use that tool, we invite you to look into the [command line interface](https://softlayer-python.readthedocs.org/en/latest/cli.html) that is part of the [git](http://github.com/softlayer/softlayer-python) project.
88

99
This documentation is also written for Ruby developers who wish to contribute to the `softlayer_api` Gem. The Gem is a work in progress. We welcome the support of the SoftLayer development community to improve the Gem. The project is open source and we hope that source will serve as a useful library, stand as sample code to assist exploration, and serve as an opportunity for developers to shape it for both those needs.
1010

0 commit comments

Comments
 (0)