Ecology of the Evergreen Developer ================================== :author: Dan Scott :copyright: 2012 Laurentian University :backend: slidy :data-uri: :max-width: 45em :duration: 45 This talk is licensed under a http://creativecommons.org/licenses/by-sa/3.0[Creative Commons, Attribution, Share Alike license]. image::images/cc_by_sa_360.png[CC BY SA] Slides and sources available at 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] The Release as the Central Artifact ----------------------------------- * Most of the Evergreen community focuses on official releases (2.0.10, 2.1.1) for their testing and communication efforts [role="incremental"] * Releases provide a common ground - local customizations aside - for comparing workflows and expected outcomes in documenting best practices and pinpointing bugs * Releases represent the culmination of efforts on the part of all contributors to develop the best possible result; a successful release is (or should be) a matter of pride for the community * All who contribute to a successful release are part of the development team, and thus can be considered developers [role="incremental"] _With apologies to MVLC, who proudly run the bleeding-edge version of Evergreen, applying updates on a weekly basis, thus finding the most egregious problems early in the cycle - we thank you!_ Who, then, are developers? -------------------------- [role="incremental"] * Anyone who writes code for OpenSRF or Evergreen is a developer: ** _Committers_: those who have the ability to commit code to release branches ** _Code contributors_: those who write and commit code to working branches or patches * _Testers / Bug wranglers_: those who test releases or branches or patches and report positive or negative results, as well as those who keep bug status information up to date * _Technical writers_: those who write documentation and submit it to the http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:dig[Documentation Interest Group] * _Translators_: Those who translate U.S. English _strings_ into a different locale (Armenian, Finnish, or Canadian English all count) * _Release team_: those who create the release tarball and publicize it on various channels Release processes ----------------- [role="incremental"] * Evergreen currently creates two http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[different kinds of releases]: [role="incremental"] ** Major/minor _feature_ releases (2.0.0, 2.1.0, 2.2.0) - in which new features are added to Evergreen ** _Patch_ releases (2.0.1, 2.0.2, 2.0.x, 2.1.1) - in which changes are limited strictly to bug fixes and updated translations [role="incremental"] * Evergreen 2.2.0 marks our first attempt to adopt a _time-based_ feature release [role="incremental"] ** Instead of defining a release by which features we plan to add, we define a release as a cumulative sum of all new features which were considered stable enough to commit to the release branch at a given point in time ** Rough agreement to target a 2.2.0 release in March 2012, with subsequent feature releases six months apart Release processes - support --------------------------- * http://markmail.org/message/53umdzope7nobtqb["Time based releases occur every 6 months with each release getting 15 months of support (12 for general bugs and 3 more for security)."] ** So, when 2.2.0 is released, the 2.1.x series will continue to be supported with patch releases, but 2.0.x will only get a new release if a security bug is found and fixed * Problem: we have not created a patch release since 2.1.1 in November 2011 * Suggestion: adopt time-based patch release cycles (monthly, if a commit has been merged?) for patch releases as well BREAKING NEWS ------------- At the ungodly time of 8:00 AM on Friday, April 27, 2012, developers agreed to create release manager and release maintainer positions * Position to last through the next major release * Establishes release schedule * Outlines major infrastructure changes for that release (based on consultation) * Elected by those willing to show up at 8:00 AM on Friday at the conference (could be opened up further) * Ensures pull requests get attention * Works with bug wrangler to ensure that master stays clean * Regular communication to the community on a timely basis * The RM is not a funnel for all commits; but will want informal assent before major commits * RM will be charged with periodically communicating the state of the release * Designated tie-breaker when we can't reach consensus on a technical issue Suckers, er, highly-esteemed volunteers --------------------------------------- * Release manager for 2.3 (or 3.0): Bill Erickson * Release maintainer for 2.2: Lebbeous Fogle-Weekley * Release maintainer for 2.1: Dan Scott Road to a release ----------------- With some definitions drawn from the Evergreen wiki http://evergreen-ils.org/dokuwiki/doku.php?id=versioning[page on versioning]: . _master_ - Code that has been reviewed, tested, and committed to the core code repository . _alpha_ - Features are mostly complete, release is intended for testing, feedback, and documentation . _beta_ - Hard cutoff for new features, database schema changes, and string changes . _release candidate_ ** Contains no show-stopper bugs ** New and updated translations can be integrated ** All functionality and upgrades from previous releases have been tested . _Golden Master_ or _Generally Available (GA)_ ** Contains no show-stopper or critical bugs ** Release notes, installation notes, and upgrade instructions are ready Committing code to the core repository -------------------------------------- . Developers commit code to _working branches_ - publicly visible copies of the code repository that contain only the changes pertinent to a particular bug or feature . When a developer is satisfied that their branch: ** Fixes the bug or completes the feature ** Does not introduce any regressions ** Is adequately documented in the release notes ** And is formatted as one or more clearly-commented commits then they mark a corresponding http://bugs.launchpad.net/evergreen[bug] with the tag *pullrequest* . Another developer reviews the associated changes, tests to ensure that no bugs were inadvertently introduced, and _signs off_ on the commits in the branch - either pushing their own working banch, or pushing the signed off commits directly into the core code repository Anatomy of a git commit message ------------------------------- [source,txt] ------------------------------------------------------------------------------ <1> commit 218722deb2a57f8b1f94869e12602c1286c10aae <2> Author: Bill Erickson Date: Wed Mar 21 14:34:19 2012 -0400 <3> TPac: non-inherited org unit visibility : hide copy counts Avoid showing copy counts for non-opac-visible org units in the search results and record details page. This is important when the 'opac.org_unit.non_inheritied_visibility' global flag is enabled, as org units along the tree may be non-visible. <4> Signed-off-by: Bill Erickson <5> Signed-off-by: Mike Rylander ------------------------------------------------------------------------------ <1> Commit hash - uniquely identifies the associated changeset <2> Author - identifies the changeset creator <3> Commit summary - brief one-line summary of associated changes <4> Author's sign-off - asserts that the author acknowledges the http://git.evergreen-ils.org/?p=Evergreen.git;a=blob_plain;f=DCO-1.1.txt;hb=refs/heads/master[Developer's Certificate of Originality] <5> Committer sign-off - asserts that this person has reviewed and tested the changeset and believes that it is ready to be part of the core repository What do developers do? ---------------------- * Create Evergreen releases * Write code to enable new features * Document * Create, find, and fix bugs * Communicate Communicate - Google Hangout ---------------------------- * Newest form of group communication * Attempted during Hackfest 2012 with underwhelming results * *Extremely* hard to search (impossible?) Communicate - Mailing lists --------------------------- * Oldest form of group communication: email * Plain text, low bandwidth, efficient * Can be hard to search - use http://dir.gmane.org/gmane.education.libraries.open-ils.devel[Gmane] or http://markmail.org/search/?q=list%3Aorg.georgialibraries.list.open-ils-dev[Markmail] * Generally referred to as the _Developer's list_ but http://evergreen-ils.org/listserv.php[Mailing lists] calls it the _Technical discussion list_ * Now mostly used for people seeking help from developers; very few threads initiated by committers Communicate - IRC ----------------- * Internet Relay Chat * *_The_* most important developer communication channel - both for day-to-day work, as well as for various meetings * Oldest form of instant messaging * Plain text, low bandwidth, efficient * *Very* hard to search - but http://evergreen-ils.org/irc_logs/evergreen/[logged] * Activity limited mostly to UTC -4/-5 developer hours Communicate - Wiki ------------------ * Enables collaborative editing of documents with version history * Searchable, particularly from within the wiki * Contains: ** Documented http://evergreen-ils.org/dokuwiki/doku.php?id=contributing[contributor processes] ** http://evergreen-ils.org/dokuwiki/doku.php?id=dev:meetings[Meeting agendas], as well as minutes (until the adoption of the *IRC Meetbot* in early 2012) ** Fragments of technical documentation (http://evergreen-ils.org/dokuwiki/doku.php?id=mozilla-devel:building_the_staff_client[Building the staff client], http://evergreen-ils.org/dokuwiki/doku.php?id=documentation:indexing[Bibliographic indexing in Evergreen]) ** Miscellaneous tips and tricks (http://evergreen-ils.org/dokuwiki/doku.php?id=scratchpad:random_magic_spells[Random magic spells]) Communicate - Launchpad ----------------------- * Evergreen's third bug tracking system, following Bugzilla and Trac ** Also includes translation management support and some release management * Relatively easy to generate http://goo.gl/uMhdC[lists of open bugs] for a given release series * Pros: ** Translations are seeded by strings from other projects ** Requires no effort to host and maintain * Some cons: ** Version control system mismatch: Launchpad uses Bazaar, we use git ** Locale name mismatch: Launchpad uses xx[_YY], Evergreen uses xx-YY Bug workflow ------------ . Bugs are added to Launchpad to report actual bugs or to track the development of new features . Testers attempt to reproduce a bug (`Confirmed`) and comment on their testing environment and/or identify causes . Developer creates a branch for a fix (or feature) and tags it `pullrequest` . Testers create signed-off branches . When the branch is committed to the core repository, the bug is marked `Fix committed` . When the code is released in an official release, the bug is marked `Fix released` Reporting a bug --------------- Developers are a lazy species with short attention spans. To increase the chances that your problem will be understood and worked on by a developer: * Describe the problem with a succinct but clear one-liner * Provide a more detailed description of the bug: ** What did you do (step by step)? ** What happened? ** What did you expect to happen? * Include a description of your environment (OpenSRF version, Evergreen version, PostgreSQL version, operating system, configuration settings, browser (if applicable)) * A screenshot may be helpful in illustrating the problem, but recognize that many developers live inside terminals * First likely response will be "Is this still happening in the most current release and/or master?" - so if you can pre-emptively test that, you can speed the process along Yamil Suarez opened some https://bugs.launchpad.net/evergreen/+bug/989391[model] https://bugs.launchpad.net/evergreen/+bug/989387[bugs] this morning Describing an enhancement ------------------------- Similar to reporting a bug, describing an enhancement ideally can be summarized by a meaningful one-liner but also includes a more detailed description. Include different scenarios for the desired functionality; some aspects to consider: * Does the catalog vs. staff client context matter? * Should this new functionality be part the default behavior, or should it be something sites have to enable? * What configuration settings are required, and where should they be set? ** User preferences ** Library settings ** opensrf.xml values ** Catalog / staff client customization Developer Glossary ------------------ * _Karma_ - a positive or negative measurement of value to the community as tracked in the IRC channel by the `pinesol` bot ** Focus is generally on the positive side for people, although karma decrements may be applied to one's own nick in wry self-admonishment ** Lowest karma currently is for `my_laptop` with `-15`, followed by `ie` with `-13` * _Tuits_, or _Round tuits_ - a fictional device that would enable the holder to accomplish all tasks that simply require time; as in "When I get around to it"