1 Ecology of the Evergreen Developer
2 ==================================
4 :copyright: 2012 Laurentian University
10 This talk is licensed under a http://creativecommons.org/licenses/by-sa/3.0[Creative Commons, Attribution, Share Alike license].
12 image::images/cc_by_sa_360.png[CC BY SA]
14 Slides and sources available at
15 http://git.evergreen-ils.org/?p=working/random.git;a=tree;h=refs/heads/user/dbs/eg2012_dev_ecology;hb=refs/heads/user/dbs/eg2012_dev_ecology[git.evergreen-ils.org:working/random.git]
17 The Release as the Central Artifact
18 -----------------------------------
20 * Most of the Evergreen community focuses on official releases (2.0.10,
21 2.1.1) for their testing and communication efforts
24 * Releases provide a common ground - local customizations aside - for
25 comparing workflows and expected outcomes in documenting best practices
27 * Releases represent the culmination of efforts on the part of all
28 contributors to develop the best possible result; a successful release is
29 (or should be) a matter of pride for the community
30 * All who contribute to a successful release are part of the development
31 team, and thus can be considered developers
34 _With apologies to MVLC, who proudly run the bleeding-edge version of
35 Evergreen, applying updates on a weekly basis, thus finding the most
36 egregious problems early in the cycle - we thank you!_
38 Who, then, are developers?
39 --------------------------
42 * Anyone who writes code for OpenSRF or Evergreen is a developer:
43 ** _Committers_: those who have the ability to commit code to release
45 ** _Code contributors_: those who write and commit code to working
47 * _Testers / Bug wranglers_: those who test releases or branches or
48 patches and report positive or negative results, as well as those
49 who keep bug status information up to date
50 * _Technical writers_: those who write documentation and submit it to
51 the http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:dig[Documentation
53 * _Translators_: Those who translate U.S. English _strings_ into a
54 different locale (Armenian, Finnish, or Canadian English all count)
55 * _Release team_: those who create the release tarball and publicize it
62 * Evergreen currently creates two
63 http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[different kinds of
67 ** Major/minor _feature_ releases (2.0.0, 2.1.0, 2.2.0) - in which new
68 features are added to Evergreen
69 ** _Patch_ releases (2.0.1, 2.0.2, 2.0.x, 2.1.1) - in which changes are
70 limited strictly to bug fixes and updated translations
73 * Evergreen 2.2.0 marks our first attempt to adopt a _time-based_ feature
77 ** Instead of defining a release by which features we plan to add, we
78 define a release as a cumulative sum of all new features which were
79 considered stable enough to commit to the release branch at a given
81 ** Rough agreement to target a 2.2.0 release in March 2012, with subsequent
82 feature releases six months apart
84 Release processes - support
85 ---------------------------
86 * http://markmail.org/message/53umdzope7nobtqb["Time based releases occur
87 every 6 months with each release getting 15 months of support (12 for
88 general bugs and 3 more for security)."]
89 ** So, when 2.2.0 is released, the 2.1.x series will continue to be
90 supported with patch releases, but 2.0.x will only get a new release
91 if a security bug is found and fixed
93 * Problem: we have not created a patch release since 2.1.1 in November 2011
94 * Suggestion: adopt time-based patch release cycles (monthly, if a commit
95 has been merged?) for patch releases as well
99 At the ungodly time of 8:00 AM on Friday, April 27, 2012, developers agreed to
100 create release manager and release maintainer positions
102 * Position to last through the next major release
103 * Establishes release schedule
104 * Outlines major infrastructure changes for that release (based on
106 * Elected by those willing to show up at 8:00 AM on Friday at the
107 conference (could be opened up further)
108 * Ensures pull requests get attention
109 * Works with bug wrangler to ensure that master stays clean
110 * Regular communication to the community on a timely basis
111 * The RM is not a funnel for all commits; but will want informal assent
113 * RM will be charged with periodically communicating the state of the
115 * Designated tie-breaker when we can't reach consensus on a technical issue
117 Suckers, er, highly-esteemed volunteers
118 ---------------------------------------
120 * Release manager for 2.3 (or 3.0): Bill Erickson
121 * Release maintainer for 2.2: Lebbeous Fogle-Weekley
122 * Release maintainer for 2.1: Dan Scott
126 With some definitions drawn from the Evergreen wiki
127 http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[page on versioning]:
129 . _master_ - Code that has been reviewed, tested, and committed to the core
131 . _alpha_ - Features are mostly complete, release is intended for testing,
132 feedback, and documentation
133 . _beta_ - Hard cutoff for new features, database schema changes, and string
135 . _release candidate_
136 ** Contains no show-stopper bugs
137 ** New and updated translations can be integrated
138 ** All functionality and upgrades from previous releases have been tested
139 . _Golden Master_ or _Generally Available (GA)_
140 ** Contains no show-stopper or critical bugs
141 ** Release notes, installation notes, and upgrade instructions are ready
143 Committing code to the core repository
144 --------------------------------------
145 . Developers commit code to _working branches_ - publicly visible copies
146 of the code repository that contain only the changes pertinent to a
147 particular bug or feature
148 . When a developer is satisfied that their branch:
149 ** Fixes the bug or completes the feature
150 ** Does not introduce any regressions
151 ** Is adequately documented in the release notes
152 ** And is formatted as one or more clearly-commented commits
153 then they mark a corresponding http://bugs.launchpad.net/evergreen[bug]
154 with the tag *pullrequest*
155 . Another developer reviews the associated changes, tests to ensure that
156 no bugs were inadvertently introduced, and _signs off_ on the commits in
157 the branch - either pushing their own working banch, or pushing the signed
158 off commits directly into the core code repository
160 Anatomy of a git commit message
161 -------------------------------
163 ------------------------------------------------------------------------------
164 <1> commit 218722deb2a57f8b1f94869e12602c1286c10aae
165 <2> Author: Bill Erickson <berick@esilibrary.com>
166 Date: Wed Mar 21 14:34:19 2012 -0400
168 <3> TPac: non-inherited org unit visibility : hide copy counts
170 Avoid showing copy counts for non-opac-visible org units in the search
171 results and record details page. This is important when the
172 'opac.org_unit.non_inheritied_visibility' global flag is enabled, as org
173 units along the tree may be non-visible.
175 <4> Signed-off-by: Bill Erickson <berick@esilibrary.com>
176 <5> Signed-off-by: Mike Rylander <mrylander@gmail.com>
177 ------------------------------------------------------------------------------
179 <1> Commit hash - uniquely identifies the associated changeset
180 <2> Author - identifies the changeset creator
181 <3> Commit summary - brief one-line summary of associated changes
182 <4> Author's sign-off - asserts that the author acknowledges the
183 http://git.evergreen-ils.org/?p=Evergreen.git;a=blob_plain;f=DCO-1.1.txt;hb=refs/heads/master[Developer's
184 Certificate of Originality]
185 <5> Committer sign-off - asserts that this person has reviewed and tested
186 the changeset and believes that it is ready to be part of the core
189 What do developers do?
190 ----------------------
191 * Create Evergreen releases
192 * Write code to enable new features
194 * Create, find, and fix bugs
197 Communicate - Google Hangout
198 ----------------------------
199 * Newest form of group communication
200 * Attempted during Hackfest 2012 with underwhelming results
201 * *Extremely* hard to search (impossible?)
203 Communicate - Mailing lists
204 ---------------------------
205 * Oldest form of group communication: email
206 * Plain text, low bandwidth, efficient
207 * Can be hard to search - use
208 http://dir.gmane.org/gmane.education.libraries.open-ils.devel[Gmane] or
209 http://markmail.org/search/?q=list%3Aorg.georgialibraries.list.open-ils-dev[Markmail]
210 * Generally referred to as the _Developer's list_ but
211 http://evergreen-ils.org/listserv.php[Mailing lists] calls it the
212 _Technical discussion list_
213 * Now mostly used for people seeking help from developers; very few threads
214 initiated by committers
218 * Internet Relay Chat
219 * *_The_* most important developer communication channel - both for
220 day-to-day work, as well as for various meetings
221 * Oldest form of instant messaging
222 * Plain text, low bandwidth, efficient
223 * *Very* hard to search - but http://evergreen-ils.org/irc_logs/evergreen/[logged]
224 * Activity limited mostly to UTC -4/-5 developer hours
228 * Enables collaborative editing of documents with version history
229 * Searchable, particularly from within the wiki
231 ** Documented http://evergreen-ils.org/dokuwiki/doku.php?id=contributing[contributor
233 ** http://evergreen-ils.org/dokuwiki/doku.php?id=dev:meetings[Meeting
234 agendas], as well as minutes (until the adoption of the *IRC Meetbot* in
236 ** Fragments of technical documentation
237 (http://evergreen-ils.org/dokuwiki/doku.php?id=mozilla-devel:building_the_staff_client[Building
238 the staff client], http://evergreen-ils.org/dokuwiki/doku.php?id=documentation:indexing[Bibliographic
239 indexing in Evergreen])
240 ** Miscellaneous tips and tricks
241 (http://evergreen-ils.org/dokuwiki/doku.php?id=scratchpad:random_magic_spells[Random
244 Communicate - Launchpad
245 -----------------------
246 * Evergreen's third bug tracking system, following Bugzilla and Trac
247 ** Also includes translation management support and some release management
248 * Relatively easy to generate http://goo.gl/uMhdC[lists of open bugs] for a
251 ** Translations are seeded by strings from other projects
252 ** Requires no effort to host and maintain
254 ** Version control system mismatch: Launchpad uses Bazaar, we use git
255 ** Locale name mismatch: Launchpad uses xx[_YY], Evergreen uses xx-YY
259 . Bugs are added to Launchpad to report actual bugs or to track the
260 development of new features
261 . Testers attempt to reproduce a bug (`Confirmed`) and comment on their
262 testing environment and/or identify causes
263 . Developer creates a branch for a fix (or feature) and tags it
265 . Testers create signed-off branches
266 . When the branch is committed to the core repository, the bug is marked
268 . When the code is released in an official release, the bug is marked
273 Developers are a lazy species with short attention spans. To increase the
274 chances that your problem will be understood and worked on by a developer:
276 * Describe the problem with a succinct but clear one-liner
277 * Provide a more detailed description of the bug:
278 ** What did you do (step by step)?
280 ** What did you expect to happen?
281 * Include a description of your environment (OpenSRF version, Evergreen
282 version, PostgreSQL version, operating system, configuration settings,
283 browser (if applicable))
284 * A screenshot may be helpful in illustrating the problem, but recognize
285 that many developers live inside terminals
286 * First likely response will be "Is this still happening in the most current
287 release and/or master?" - so if you can pre-emptively test that, you
288 can speed the process along
290 Yamil Suarez opened some https://bugs.launchpad.net/evergreen/+bug/989391[model]
291 https://bugs.launchpad.net/evergreen/+bug/989387[bugs] this morning
293 Describing an enhancement
294 -------------------------
295 Similar to reporting a bug, describing an enhancement ideally can be
296 summarized by a meaningful one-liner but also includes a more detailed
299 Include different scenarios for the desired functionality; some aspects
302 * Does the catalog vs. staff client context matter?
303 * Should this new functionality be part the default behavior, or
304 should it be something sites have to enable?
305 * What configuration settings are required, and where should they be set?
308 ** opensrf.xml values
309 ** Catalog / staff client customization
313 * _Karma_ - a positive or negative measurement of value to the community
314 as tracked in the IRC channel by the `pinesol` bot
315 ** Focus is generally on the positive side for people, although karma
316 decrements may be applied to one's own nick in wry self-admonishment
317 ** Lowest karma currently is for `my_laptop` with `-15`, followed by
319 * _Tuits_, or _Round tuits_ - a fictional device that would enable the
320 holder to accomplish all tasks that simply require time; as in "When I get