1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
= 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
* Ruby 1.8.6 or greater
=== Build
* rubygems 0.9.0 or greater
* rake 0.8.3 or greater
* mspec 1.5.9 (optional - used for testing)
* allison 2.0.3 (optional - used for documentation only, if available)
* rsync (optional - used for publishing documentation)
=== Install
* rubygems 0.9.0 or greater
== Versioning Policy
Version numbers will be in <em>x.y.z</em> format, where <em>x</em>, <em>y</em>,
and <em>z</em> are integers starting from 0. The version increment rules are
as follows:
<b>x</b>:: Planned releases which implement significant changes and/or break API
compatibility. An exception is to be made for the transition from
the <em>0.y.z</em> series to the <em>1.y.z</em> series since the
<em>0.y.z</em> series is expected to be unstable throughout
development. When incremented, <em>y</em> and <em>z</em> are reset
to 0.
<b>y</b>:: Planned releases which incorporate numerous bug fixes and/or new
features which do not break backward compatibility. When
incremented, <em>z</em> is reset to 0.
<b>z</b>:: Generally, unplanned releases which incorporate a single fix for a
critical defect.
This is the {Rational Versioning Policy}[http://www.rubygems.org/read/chapter/7]
as outlined in the {RubyGems User Guide}[http://www.rubygems.org/read/book/1].
== 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.
<b>File Encoding</b>:: UTF-8
<b>Indentation</b>:: Two spaces; no tabs
<b>Comments</b>:: Document classes, attributes, methods, and code
<b>Boolean Operators</b>:: Use <tt>&&</tt> and <tt>||</tt> for boolean tests;
avoid <tt>and</tt> and <tt>or</tt>
<b>Method Calls</b>:: Use <tt>a_method(arg, arg, etc)</tt>; <b>not</b>
<tt>a_method( arg, arg, etc )</tt>,
<tt>a_method arg, arg, etc</tt>, or any other
variation
<b>Blocks</b>:: <tt>do end</tt> for multi-line blocks and
<tt>{ }</tt> for single-line blocks
<b>Line length</b>:: Limit lines to a maximum of 80 characters
<b>General</b>:: Try to follow the flow and style of the rest of the
code
== Generating Patches
Patches should usually be generated against the <em>HEAD</em> revision of the
<em>master</em> 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.
|
