Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 156 lines (104 sloc) 5.854 kB
8ce06a1 @flavorjones Y U NO GEMSPEC!?
flavorjones authored
1 (note: this was originally a blog post published at http://blog.flavorjon.es/2012/03/y-u-no-gemspec.html)
2
3 ## tl;dr
4
5 1. Team Nokogiri are not 10-foot-tall code-crunching robots, so `master` is usually unstable.
6 2. Unstable code can corrupt your data and crash your application, which would make everybody look bad.
7 3. Therefore, the _risk_ associated with using unstable code is severe; for you _and_ for Team Nokogiri.
8 4. The absence of a gemspec is a risk mitigation tactic.
9 5. You can always ask for an RC release.
10
11
12 ## Why Isn't There a Gemspec!?
13
14 OHAI! Thank you for asking this question!
15
16 Team Nokogiri gets asked this pretty frequently. Just a sample from
17 the historical record:
18
e271ebd @flavorjones More tenderlove -> sparklemotion
flavorjones authored
19 * [Issue #274](https://github.com/sparklemotion/nokogiri/issues/274)
20 * [Issue #371](https://github.com/sparklemotion/nokogiri/issues/371)
21 * [A commit removing nokogiri.gemspec](https://github.com/sparklemotion/nokogiri/commit/7f17a643a05ca381d65131515b54d4a3a61ca2e1#commitcomment-667477)
8ce06a1 @flavorjones Y U NO GEMSPEC!?
flavorjones authored
22 * [A nokogiri-talk thread](http://groups.google.com/group/nokogiri-talk/browse_thread/thread/4706b002e492d23f)
23 * [Another nokogiri-talk thread](http://groups.google.com/group/nokogiri-talk/browse_thread/thread/0b201bb80ea3eea0)
24
25 Sometimes people imply that we've forgotten, or that we don't how to
26 properly manage our codebase. Those people are super fun to respond
27 to!
28
29 We've gone back and forth a couple of times over the past few years,
30 but the current policy of Team Nokogiri is to **not** provide a
31 gemspec in the Github repo. This is a conscious choice, not an
32 oversight.
33
34
35 ## But You Didn't Answer the Question!
36
37 Ah, I was hoping you wouldn't notice. Well, OK, let's do this, if
38 you're serious about it.
39
40 I'd like to start by talking about _risk_. Specifically, the risk
41 associated with using a known-unstable version of Nokogiri.
42
43
44 ### Risk
45
46 One common way to evaluate the _risk_ of an incident is:
47
48 risk = probability x impact
49
50 You can read more about this on [the internets](http://en.wikipedia.org/wiki/Risk_Matrix).
51
52 The _risk_ associated with a Nokogiri bug could be loosely defined by
53 answering the questions:
54
55 * "How likely is it that a bug exists?" (probability)
56 * "How severe will the consequences of a bug be?" (impact)
57
58
59 ### Probability
60
61 The `master` branch should be considered unstable. Team Nokogiri are
62 not 10-foot-tall code-crunching robots; we are humans. We make
63 mistakes, and as a result, any arbitrary commit on `master` is likely
64 to contain bugs.
65
66 Just as an example, Nokogiri `master` was unstable for about five
67 months between November 2011 and March 2012. It was unstable not
68 because we were sloppy, or didn't care, but because the fixes were
69 hard and unobvious.
70
71 When we release Nokogiri, we test for memory leaks and invalid memory
72 access on all kinds of platforms with many flavors of Ruby and lots of
73 versions of libxml2. Because these tests are time-consuming, we don't
74 run them on every commit. We run them often when preparing a release.
75
76 If we're releasing Nokogiri, it means we think it's rock solid.
77
78 And if we're not releasing it, it means there are probably bugs.
79
80
81 ### Impact
82
83 Nokogiri is a gem with native extensions. This means it's not pure
84 Ruby -- there's C or Java code being compiled and run, which means
85 that there's always a chance that the gem will crash your application,
86 or worse. Possible outcomes include:
87
88 * leaking memory
89 * corrupting data
90 * making benign code crash (due to memory corruption)
91
92 So, then, a bug in a native extension can have much worse downside
93 than you might think. It's not just going to do something unexpected;
94 it's possibly going to do terrible, awful things to your application
95 and data.
96
97 **Nobody** wants that to happen. Especially Team Nokogiri.
98
99
100 ### Risk, Redux
101
102 So, if you accept the equation
103
104 risk = probability x impact
105
106 and you believe me when I say that:
107
108 * the probablility of a bug in unreleased code is high, and
109 * the impact of a bug is likely to be severe,
110
111 then you should easily see that the _risk_ associated with a bug in
112 Nokogiri is quite high.
113
114 Part of Team Nokogiri's job is to try to mitigate this risk. We have a
115 number of tactics that we use to accomplish this:
116
117 * we respond quickly to bug reports, particularly when they are possible memory issues
118 * we review each others' commits
119 * we have a thorough test suite, and we test-drive new features
120 * we discuss code design and issues on a core developer mailing list
121 * we use valgrind to test for memory issues (leaks and invalid
122 access) on multiple combinations of OS, libxml2 and Ruby
123 * we package release candidates, and encourage devs to use them
124 * **we do NOT commit a gemspec in our git repository**
125
126 Yes, that's right, the absence of a gemspec is a risk mitigation
127 tactic. Not only does Team Nokogiri not want to imply support for
128 `master`, we want to **actively discourage** people from using
129 it. Because it's not stable.
130
131
132 ## But I Want to Do It Anyway
133
134 Another option, is to email the [nokogiri-talk
135 list](http://groups.google.com/group/nokogiri-talk) and ask for a
136 release candidate to be built. We're pretty accommodating if there's a
137 bugfix that's a blocker for you. And if we can't release an RC, we'll
138 tell you why.
139
140 And in the end, nothing is stopping you from cloning the repo and
141 generating a private gemspec. This is an extra step or two, but it has
142 the benefit of making sure developers have thought through the costs
143 and risks involved; and it tends to select for developers who know
144 what they're doing.
145
146
147 ## In Conclusion
148
149 Team Nokogiri takes stability very seriously. We want everybody who
150 uses Nokogiri to have a pleasant experience. And so we want to make
151 sure that you're using the best software we can make.
152
153 Please keep in mind that we're trying very hard to do the right thing
154 for all Nokogiri users out there in Rubyland. Nokogiri loves you very
155 much, and we hope you love it back.
Something went wrong with that request. Please try again.