eg2012_ddd.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 The Release as the Central Artifact
  11 -----------------------------------
  12 (With apologies to MVLC, who proudly run the bleeding-edge version of
  13 Evergreen and apply updates on a weekly basis)
  14
  15   * Most of the Evergreen community focuses on official releases (2.0.10,
  16     2.1.1) for their testing and communication efforts
  17   * Releases provide a common ground - local customizations aside - for
  18     comparing workflows and expected outcomes in documenting best practices
  19     and pinpointing bugs
  20   * Releases represent the culmination of efforts on the part of all
  21     contributors to develop the best possible result; a successful release is
  22     (or should be) a matter of pride for the community
  23   * All who contribute to a successful release are part of the development
  24     team, and thus can be considered developers
  25
  26 Who, then, are developers?
  27 --------------------------
  28
  29 [role="incremental"]
  30   * Anyone who writes code for OpenSRF or Evergreen is a developer:
  31     ** _Committers_: those who have the ability to commit code to release
  32        branches
  33     ** _Code contributors_: those who write and commit code to working
  34        branches or patches
  35   * _Testers / Bug wranglers_: those who test releases or branches or
  36     patches and report positive or negative results, as well as those
  37     who keep bug status information up to date
  38   * _Technical writers_: those who write documentation and submit it to
  39     the http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:dig[Documentation
  40     Interest Group]
  41   * _Translators_: Those who translate U.S. English _strings_ into a
  42     different locale (Armenian, Finnish, or Canadian English all count)
  43   * _Release team_: those who create the release tarball and publicize it
  44     on various channels
  45
  46 Release processes
  47 -----------------
  48
  49 [role="incremental"]
  50   * Evergreen currently creates two
  51     http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[different kinds of
  52     releases]:
  53
  54 [role="incremental"]
  55     ** Major/minor _feature_ releases (2.0.0, 2.1.0, 2.2.0) - in which new
  56        features are added to Evergreen
  57     ** _Patch_ releases (2.0.1, 2.0.2, 2.0.x, 2.1.1) - in which changes are
  58        limited strictly to bug fixes and updated translations
  59
  60 [role="incremental"]
  61   * Evergreen 2.2.0 marks our first attempt to adopt a _time-based_ feature
  62     release
  63
  64 [role="incremental"]
  65     ** Instead of defining a release by which features we plan to add, we
  66        define a release as a cumulative sum of all new features which were
  67        considered stable enough to commit to the release branch at a given
  68        point in time
  69     ** Rough agreement to target a 2.2.0 release in March 2012, with subsequent
  70        feature releases six months apart
  71
  72 Release processes - support
  73 ---------------------------
  74   * http://markmail.org/message/53umdzope7nobtqb["Time based releases occur
  75     every 6 months with each release getting 15 months of support (12 for
  76     general bugs and 3 more for security)."]
  77     ** So, when 2.2.0 is released, the 2.1.x series will continue to be
  78        supported with patch releases, but 2.0.x will only get a new release
  79        if a security bug is found and fixed
  80
  81   * Problem: we have not created a patch release since 2.1.1 in November 2011
  82   * Suggestion: adopt time-based patch release cycles (monthly, if a commit
  83     has been merged?) for patch releases as well
  84
  85 Road to a release
  86 -----------------
  87 With some definitions drawn from the Evergreen wiki
  88 http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[page on versioning]:
  89
  90   . _master_ - Code that has been reviewed, tested, and committed to the core
  91     code repository
  92   . _alpha_ - Features are mostly complete, release is intended for testing,
  93     feedback, and documentation
  94   . _beta_ - Hard cutoff for new features, database schema changes, and string
  95     changes
  96   . _release candidate_
  97     ** Contains no show-stopper bugs
  98     ** New and updated translations can be integrated
  99     ** All functionality and upgrades from previous releases have been tested
 100   . _Golden Master_ or _Generally Available (GA)_
 101     ** Contains no show-stopper or critical bugs
 102     ** Release notes, installation notes, and upgrade instructions are ready
 103
 104 Committing code to the core repository
 105 --------------------------------------
 106   . Developers commit code to _working branches_ - publicly visible copies
 107     of the code repository that contain only the changes pertinent to a
 108     particular bug or feature
 109   . When a developer is satisfied that their branch:
 110       ** Fixes the bug or completes the feature
 111       ** Does not introduce any regressions
 112       ** Is adequately documented in the release notes
 113       ** And is formatted as one or more clearly-commented commits
 114     then they mark a corresponding http://bugs.launchpad.net/evergreen[bug]
 115     with the tag *pullrequest*
 116   . Another developer reviews the associated changes, tests to ensure that
 117     no bugs were inadvertently introduced, and _signs off_ on the commits in
 118     the branch - either pushing their own working banch, or pushing the signed
 119     off commits directly into the core code repository
 120
 121 Anatomy of a git commit message
 122 -------------------------------
 123 [source,txt]
 124 ------------------------------------------------------------------------------
 125 <1> commit 218722deb2a57f8b1f94869e12602c1286c10aae
 126 <2> Author: Bill Erickson <berick@esilibrary.com>
 127     Date:   Wed Mar 21 14:34:19 2012 -0400
 128
 129 <3> TPac: non-inherited org unit visibility : hide copy counts
 130
 131     Avoid showing copy counts for non-opac-visible org units in the search
 132     results and record details page.  This is important when the
 133     'opac.org_unit.non_inheritied_visibility' global flag is enabled, as org
 134     units along the tree may be non-visible.
 135
 136 <4> Signed-off-by: Bill Erickson <berick@esilibrary.com>
 137 <5> Signed-off-by: Mike Rylander <mrylander@gmail.com>
 138 ------------------------------------------------------------------------------
 139
 140 <1> Commit hash - uniquely identifies the associated changeset
 141 <2> Author - identifies the changeset creator
 142 <3> Commit summary - brief one-line summary of associated changes
 143 <4> Author's sign-off - asserts that the author acknowledges the
 144     http://git.evergreen-ils.org/?p=Evergreen.git;a=blob_plain;f=DCO-1.1.txt;hb=refs/heads/master[Developer's
 145     Certificate of Originality]
 146 <5> Committer sign-off - asserts that this person has reviewed and tested
 147     the changeset and believes that it is ready to be part of the core
 148     repository
 149
 150 What do developers do?
 151 ----------------------
 152   * Create Evergreen releases
 153   * Write code to enable new features
 154   * Document
 155   * Create, find, and fix bugs
 156   * Communicate
 157
 158 Communicate - Google Hangout
 159 ----------------------------
 160   * Newest form of group communication
 161   * Attempted during Hackfest 2012 with underwhelming results
 162   * *Extremely* hard to search (impossible?)
 163
 164 Communicate - Mailing lists
 165 ---------------------------
 166   * Oldest form of group communication: email
 167   * Plain text, low bandwidth, efficient
 168   * Can be hard to search - use
 169     http://dir.gmane.org/gmane.education.libraries.open-ils.devel[Gmane] or
 170     http://markmail.org/search/?q=list%3Aorg.georgialibraries.list.open-ils-dev[Markmail]
 171   * Generally referred to as the _Developer's list_ but
 172     http://evergreen-ils.org/listserv.php[Mailing lists] calls it the
 173     _Technical discussion list_
 174   * Now mostly used for people seeking help from developers; very few threads
 175     initiated by committers
 176
 177 Communicate - IRC
 178 -----------------
 179   * Internet Relay Chat
 180   * *_The_* most important developer communication channel - both for
 181     day-to-day work, as well as for various meetings
 182   * Oldest form of instant messaging
 183   * Plain text, low bandwidth, efficient
 184   * *Very* hard to search - but http://evergreen-ils.org/irc_logs/evergreen/[logged]
 185   * Activity limited mostly to UTC -4/-5 developer hours
 186
 187 Communicate - Wiki
 188 ------------------
 189   * Enables collaborative editing of documents with version history
 190   * Searchable, particularly from within the wiki
 191   * Contains:
 192     ** Documented http://evergreen-ils.org/dokuwiki/doku.php?id=contributing[contributor
 193        processes]
 194     ** http://evergreen-ils.org/dokuwiki/doku.php?id=dev:meetings[Meeting
 195        agendas], as well as minutes (until the adoption of the *IRC Meetbot* in
 196        early 2012)
 197     ** Fragments of technical documentation
 198         (http://evergreen-ils.org/dokuwiki/doku.php?id=mozilla-devel:building_the_staff_client[Building
 199         the staff client], http://evergreen-ils.org/dokuwiki/doku.php?id=documentation:indexing[Bibliographic
 200         indexing in Evergreen])
 201     ** Miscellaneous tips and tricks
 202        (http://evergreen-ils.org/dokuwiki/doku.php?id=scratchpad:random_magic_spells[Random
 203        magic spells])
 204
 205 Communicate - Launchpad
 206 -----------------------
 207   * Evergreen's third bug tracking system, following Bugzilla and Trac
 208     ** Also includes translation management support and some release management
 209   * Relatively easy to generate http://goo.gl/uMhdC[lists of open bugs] for a
 210     given release series
 211   * Pros:
 212     ** Translations are seeded by strings from other projects
 213     ** Requires no effort to host and maintain
 214   * Some cons:
 215     ** Version control system mismatch: Launchpad uses Bazaar, we use git
 216     ** Locale name mismatch: Launchpad uses xx[_YY], Evergreen uses xx-YY
 217
 218 Bug workflow
 219 ------------
 220   . Bugs are added to Launchpad to report actual bugs or to track the
 221     development of new features
 222   . Testers attempt to reproduce a bug (`Confirmed`) and comment on their
 223     testing environment and/or identify causes
 224   . Developer creates a branch for a fix (or feature) and tags it
 225     `pullrequest`
 226   . Testers create signed-off branches
 227   . When the branch is committed to the core repository, the bug is marked
 228     `Fix committed`
 229   . When the code is released in an official release, the bug is marked
 230     `Fix released`
 231
 232 Reporting a bug
 233 ---------------
 234 Developers are a lazy species with short attention spans. To increase the
 235 chances that your problem will be understood and worked on by a developer:
 236
 237   * Describe the problem with a succinct but clear one-liner
 238   * Provide a more detailed description of the bug:
 239     ** What did you do (step by step)?
 240     ** What happened?
 241     ** What did you expect to happen?
 242   * Include a description of your environment (OpenSRF version, Evergreen
 243     version, PostgreSQL version, operating system, configuration settings,
 244     browser (if applicable))
 245   * A screenshot may be helpful in illustrating the problem, but recognize
 246     that many developers live inside terminals
 247
 248 Describing an enhancement
 249 -------------------------
 250 Similar to reporting a bug, describing an enhancement ideally can be
 251 summarized by a meaningful one-liner but also includes a more detailed
 252 description.
 253
 254 Include different scenarios for the desired functionality; some aspects
 255 to consider:
 256
 257   * Does the catalog vs. staff client context matter?
 258   * Should this new functionality be part the default behavior, or
 259     should it be something sites have to enable?
 260   * What configuration settings are required, and where should they be set?
 261       ** User preferences
 262       ** Library settings
 263       ** opensrf.xml values
 264       ** Catalog / staff client customization
 265
 266 Developer Glossary
 267 ------------------
 268   * _Tuits_, or _Round tuits_ - a fictional device that would enable the
 269     holder to accomplish all tasks that simply require time; as in "When I get
 270     around to it"
 271