i'm confounded by this:
http://docs.rubygems.org/read/chapter/7 section 6.5:
6.5 Examples
Let's work through a project lifecycle using our Stack example from above.
[eg 0]
* Version 0.0.1: The initial Stack class is release.
[eg 1]
* Version 0.0.2: Switched to a linked=list implementation because it is
cooler.
[eg 2]
* Version 0.1.0: Added a depth method.
[eg 3]
* Version 1.0.0: Added top and made pop return nil (pop used to return
the old top item).
[eg 4]
* Version 1.1.0: push now returns the value pushed (it used it return
nil).
[eg 5]
* Version 1.1.1: Fixed a bug in the linked list implementation.
[eg 6]
* Version 1.1.2: Fixed a bug introduced in the last fix.
two of these are quite confusing:
* Version 0.0.1: The initial Stack class is release.
why on earth would all digits begin numbering at zero __except__ build?
seems that it should be version 0.0.0
* Version 1.1.0: push now returns the value pushed (it used it return nil).
why would this not be 2.0.0 - remembering we're at 1.0.0 from 'eg 3'?
clearly code which had done
values.inject(stack){|accum, val| accum.push val or accum}
would no longer work. i realize this is contrived - but changing a
return type is a red flag for non-backward compatibility and the
handling in this example seems at odds with that of 'eg 3'. the fact
that a return value changed from 'nothing' to 'something' is still a
change that some code somewhere may depend upon right? or am i missing
something? bang methods are particularly sensitive to this exact kind
of change, here is a less contrived example:
version : 0.0.0
class List
def uniq!
u =
each{|elem| u << elem unless u.include? elem}
changed = u.size == self.size
self.replace u
changed ? self : nil
end
end
list = List[ 42 ]
list.uniq! or abort "nothing done!"
clearly you cannot promise backwards compatiblity via
version : 0.1.0
class List
def uniq!
u =
each{|elem| u << elem unless u.include? elem}
changed = u.size == self.size
self.replace u
self
end
end
list = List[ 42 ]
list.uniq! or abort "nothing done!"
the second __must__ become verion 1.0.0 since the implementation has
changed in an incompatible way. in short - method input/output changes
__always__ require a major increment unless done extremely carefully as
in
def notify file
end
def notify file, lineno = nil
end
but even this is risky (and wrong) since the client code may well have
coded something like this
def notify lexer
meth =
begin
lexer.method 'notify'
rescue NameError
raise "bad lexer object"
end
case meth.arity
when 1
lexer.notify __file__
when -2
lexer.notify __file__, __lineno__
else
raise "bad lexer object"
end
end
which is all a fantastic reason to write methods with signatures like:
def required_argument, options = {}
end
since you can accept new options without breaking your method signature
-- though you still have to worry about return values, nil or
otherwise...
can anyone shed some light in here?
thanks.
-a