Guide to Hacking IO::Like

Licensing

Contributed code must be licensed under the same license as this project. See the included LICENSE file for details. Special consideration MAY be made in some cases, but such cases will be rare.

Dependencies

Runtime

Build

Install

Versioning Policy

Version numbers will be in x.y.z format, where x, y, and z are integers starting from 0. The version increment rules are as follows:

x

Planned releases which implement significant changes and/or break API compatibility. An exception is to be made for the transition from the 0.y.z series to the 1.y.z series since the 0.y.z series is expected to be unstable throughout development. When incremented, y and z are reset to 0.

y

Planned releases which incorporate numerous bug fixes and/or new features which do not break backward compatibility. When incremented, z is reset to 0.

z

Generally, unplanned releases which incorporate a single fix for a critical defect.

This is the Rational Versioning Policy as outlined in the RubyGems User Guide.

Support Policy

Due to limitations in resources (time/money/manpower), this project will focus primarily upon the development line of the current release at any given time. Fixes and new features should be applied first to that development line and then backported to earlier releases if necessary and feasible. Long term maintenance of previous releases is not planned. Users are generally expected to upgrade to the latest release in order to receive updates unless an explicit declaration of support for a previous release is made.

Coding Style

The following points are not necessarily set in stone but should rather be used as a good guideline. Consistency is the goal of coding style, and changes will be more easily accepted if they are consistent with the rest of the code.

File Encoding

UTF-8

Indentation

Two spaces; no tabs

Comments

Document classes, attributes, methods, and code

Boolean Operators

Use && and || for boolean tests; avoid and and or

Method Calls

Use a_method(arg, arg, etc); not a_method( arg, arg, etc ), a_method arg, arg, etc, or any other variation

Blocks

do end for multi-line blocks and { } for single-line blocks

Line length

Limit lines to a maximum of 80 characters

General

Try to follow the flow and style of the rest of the code

Generating Patches

Patches should usually be generated against the HEAD revision of the master branch. When generating patches, please try to implement only a single feature or bug fix per patch. Documentation describing a patch should be included along with the patch so that the maintainer can more easily determine whether or not a patch is acceptable. Patches lacking the necessary documentation will be ignored.

Patches will be much more readily accepted if test cases are provided which verify correct operation. Such test cases should be provided within the patch rather than as a separate patch. Proper documentation, especially for user-visible APIs, is highly prized; providing accurate and detailed documentation, often in the form of rubydocs, throughout new code contributions will also increase the desirability of a patch.

If a series of patches is generated which cannot be applied individually, make sure to mention the dependency relationships in whatever medium is being used to distribute the patches. For instance, if a bug is discovered while implementing a new feature, create a patch which fixes the bug followed by a separate patch adding the feature. If the feature patch requires the bug fix patch in order to work, note that dependency in the comments for the feature patch by somehow referencing the bug fix patch.

The patch generation process in general:

$ git clone git://rubyforge.org/io-like.git  # Clone the repo and check out
                                             # the master branch.
$ cd io-like                                 # Enter the workspace.
(make and test changes)
$ git add file1 file2 ..                     # Add new/modified files.
$ git commit                                 # Commit changes.
$ git format-patch -C HEAD^                  # Create a patch for the last
                                             # commit.

Repeat as necessary until all patches are generated. Then either attach them to 1 or more email messages addressed to the maintainer or attach them to tickets in the issue tracker for the project. Remember to include a brief description of the patch and its dependencies, if any.