eg2012_developer_ecology.txt

   1 Ecology of the Evergreen Developer
   2 ==================================
   3 :author: Dan Scott
   4 :copyright: 2012 Laurentian University
   5 :backend: slidy
   6 :data-uri:
   7 :max-width: 45em
   8 :duration: 45
   9
  10 This talk is licensed under a http://creativecommons.org/licenses/by-sa/3.0[Creative Commons, Attribution, Share Alike license].
  11
  12 image::images/cc_by_sa_360.png[CC BY SA]
  13
  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]
  16
  17 The Release as the Central Artifact
  18 -----------------------------------
  19
  20   * Most of the Evergreen community focuses on official releases (2.0.10,
  21     2.1.1) for their testing and communication efforts
  22
  23 [role="incremental"]
  24   * Releases provide a common ground - local customizations aside - for
  25     comparing workflows and expected outcomes in documenting best practices
  26     and pinpointing bugs
  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
  32
  33 [role="incremental"]
  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!_
  37
  38 Who, then, are developers?
  39 --------------------------
  40
  41 [role="incremental"]
  42   * Anyone who writes code for OpenSRF or Evergreen is a developer:
  43     ** _Committers_: those who have the ability to commit code to release
  44        branches
  45     ** _Code contributors_: those who write and commit code to working
  46        branches or patches
  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
  52     Interest Group]
  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
  56     on various channels
  57
  58 Release processes
  59 -----------------
  60
  61 [role="incremental"]
  62   * Evergreen currently creates two
  63     http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[different kinds of
  64     releases]:
  65
  66 [role="incremental"]
  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
  71
  72 [role="incremental"]
  73   * Evergreen 2.2.0 marks our first attempt to adopt a _time-based_ feature
  74     release
  75
  76 [role="incremental"]
  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
  80        point in time
  81     ** Rough agreement to target a 2.2.0 release in March 2012, with subsequent
  82        feature releases six months apart
  83
  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
  92
  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
  96
  97 BREAKING NEWS
  98 -------------
  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
 101
 102   * Position to last through the next major release
 103   * Establishes release schedule
 104   * Outlines major infrastructure changes for that release (based on
 105     consultation)
 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
 112     before major commits
 113   * RM will be charged with periodically communicating the state of the
 114     release
 115   * Designated tie-breaker when we can't reach consensus on a technical issue
 116
 117 Suckers, er, highly-esteemed volunteers
 118 ---------------------------------------
 119
 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
 123
 124 Road to a release
 125 -----------------
 126 With some definitions drawn from the Evergreen wiki
 127 http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[page on versioning]:
 128
 129   . _master_ - Code that has been reviewed, tested, and committed to the core
 130     code repository
 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
 134     changes
 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
 142
 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
 159
 160 Anatomy of a git commit message
 161 -------------------------------
 162 [source,txt]
 163 ------------------------------------------------------------------------------
 164 <1> commit 218722deb2a57f8b1f94869e12602c1286c10aae
 165 <2> Author: Bill Erickson <berick@esilibrary.com>
 166     Date:   Wed Mar 21 14:34:19 2012 -0400
 167
 168 <3> TPac: non-inherited org unit visibility : hide copy counts
 169
 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.
 174
 175 <4> Signed-off-by: Bill Erickson <berick@esilibrary.com>
 176 <5> Signed-off-by: Mike Rylander <mrylander@gmail.com>
 177 ------------------------------------------------------------------------------
 178
 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
 187     repository
 188
 189 What do developers do?
 190 ----------------------
 191   * Create Evergreen releases
 192   * Write code to enable new features
 193   * Document
 194   * Create, find, and fix bugs
 195   * Communicate
 196
 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?)
 202
 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
 215
 216 Communicate - IRC
 217 -----------------
 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
 225
 226 Communicate - Wiki
 227 ------------------
 228   * Enables collaborative editing of documents with version history
 229   * Searchable, particularly from within the wiki
 230   * Contains:
 231     ** Documented http://evergreen-ils.org/dokuwiki/doku.php?id=contributing[contributor
 232        processes]
 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
 235        early 2012)
 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
 242        magic spells])
 243
 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
 249     given release series
 250   * Pros:
 251     ** Translations are seeded by strings from other projects
 252     ** Requires no effort to host and maintain
 253   * Some cons:
 254     ** Version control system mismatch: Launchpad uses Bazaar, we use git
 255     ** Locale name mismatch: Launchpad uses xx[_YY], Evergreen uses xx-YY
 256
 257 Bug workflow
 258 ------------
 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
 264     `pullrequest`
 265   . Testers create signed-off branches
 266   . When the branch is committed to the core repository, the bug is marked
 267     `Fix committed`
 268   . When the code is released in an official release, the bug is marked
 269     `Fix released`
 270
 271 Reporting a bug
 272 ---------------
 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:
 275
 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)?
 279     ** What happened?
 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
 289
 290 Yamil Suarez opened some https://bugs.launchpad.net/evergreen/+bug/989391[model]
 291 https://bugs.launchpad.net/evergreen/+bug/989387[bugs] this morning
 292
 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
 297 description.
 298
 299 Include different scenarios for the desired functionality; some aspects
 300 to consider:
 301
 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?
 306       ** User preferences
 307       ** Library settings
 308       ** opensrf.xml values
 309       ** Catalog / staff client customization
 310
 311 Developer Glossary
 312 ------------------
 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
 318       `ie` with `-13`
 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
 321     around to it"
 322