Page tree
Skip to end of metadata
Go to start of metadata

Table of Contents

Background

  • Why are we building the UX Pattern Library?
  • Why are we building the UI Toolkit?
  • Why is it separate from the UX Pattern Library?
    • http://ux.edx.org/
    • Very different concerns: HTML/CSS best practices versus reusable JavaScript libraries
    • There are overlaps
      • Components will output pattern library-compliant HTML
      • Will style with Pattern Library CSS if available
      • However, can be styled independently, e.g. in edx-platform

Objectives

  • Transition the ownership of the pattern library to the engineering organization
    • Develop a few simple patterns to understand the end-to-end workflow
    • Document the process followed along with best practices learned
    • Create a new FedX JIRA board and migrate all the issues out of the Pattern Library board (which follow the UX process)
  • Kickstart usage of both the pattern library and the UI Toolkit
    • Add both libraries incrementally to edx-platform (no big bang)
    • Work through all the inevitable compatibility issues
  • Allow the Open edX community to be successful with both the pattern library and the UI Toolkit
    • Provide documentation and best practices
    • Provide successful example usages of both libraries
    • Document how the process for extending the libraries
  • Demonstrate value from the project
    • Upgrade the Open edX web certs library to use edx-platform
    • Migrate the pagination views from edx-platform to the UI Toolkit
    • Work with Solutions to develop patterns needed for their upcoming projects
  • Make the two libraries self-sustaining
    • Dedicated team only necessary to get things kickstarted
    • Empower the teams to take ownership as they need new patterns
    • Give a lunch-and-learn to talk through the steps
  • Non-goals
    • Complete set of components/patterns

Outcomes

  • Target audience
    • edX developers (both edX and wider community)
      • Reduced dependency on limited UX resources
      • Speed of implementation through component reuse and established patterns
      • Reduce redundancy which avoids introducing new technical debt
      • UI consistency
      • Documented best practices which helps with onboarding and the community
      • Performance increase with reduced CSS and JS size
      • Allows UI to be separated into multiple repositories
    • UX team
      • Increase efficiency of design phase
      • Reduce redundancy which leads to technical debt
      • Design consistency
      • Allow UX team to get out of the front end development business
      • Responsive design and improved mobile support
    • Business/Product teams
      • Quicker implementation of new features
      • Fewer UX resources required to implement new designs
      • Responsive design and improved mobile support
    • Learners
      • UI consistency
      • Increased performance (due to reduced CSS and JS size)
      • New features added more frequently
    • Open edX deployed instance owners
      • Support for comprehensive theming
      • Performance increase with reduced CSS and JS size
      • Responsive design and improved mobile support
    • XBlock developers
      • first phase: don't hurt existing XBlock rendering
      • non-goal: pattern library/UI Toolkit for XBlock developers
      • does it even make sense to use the edX pattern library?
      • documented best practices for how to write an XBlock and have it work within edX platform (and other containers)

Plan

  • Overall approach
    • Small agile stories that introduce business value
    • What is the minimum piece that we can bite off first?
      • Use pattern library for Open Web Certs in the edx-platform
      • Implement pagination in the UI Toolkit and use it in edx-platform (ready for Otto and Analytics)
  • Spin up a new team (FedX)
  • Update edx-platform to use the UX Pattern Library (EPIC)
    • Update install_prereqs  (STORY)
      • add this to the paver command: npm install
      • devops is provisionally okay with this (versus checking in files into vendor) as other IDAs are doing this already
      • what happens if npm repository is down? Does that mean that an AMI build would fail?
        • can we have a backup plan?
      • should confirm with devops as we get further along
    • Update pipeline (STORY)
      • change sass compilation to import as needed from the pattern library
      • static assets need to be served through the Django pipeline (for both)
      • determine how to tie into comprehensive theming
      • do we need new paver commands? Just update the existing ones?
    • Implement theming (STORY)
      • Open edX theming version
      • edX theme (for edX color variables etc)
    • Update Open Web Certs (UXPL-21)
    • sync up pattern library JavaScript with Toolkit standards (UXPL-25)
      • primarily used for font fallback logic
      • https://github.com/filamentgroup/a-font-garde
      • edX-specific font handling code
      • should this use RequireJS? Probably simpler to just add libraries into main-application.js
        • can we just remove all JS from the UXPL project and say it lives in the UI Toolkit?
    • Focus on incremental adoption
      • Introduce pattern library into pages that are standalone
      • Much longer project to switch over the LMS courseware (XBlocks etc)
  • Update edx-platform to use the UI Toolkit (EPIC)
    • Complete the first cut of the Toolkit
      • switch from Bower to npm for UI Toolkit (STORY) and UX Pattern Library (STORY - DONE)
      • Add code coverage reporting to Travis (STORY)
      • Communicate the Toolkit's existence to edx-code and the arch council (STORY - DONE)
    • Upgrade pre-requisites
      • Upgrade JQuery (or can that wait?): 1.7.2 => 1.11.1 (or => 2.1.1) (STORY)
      • Upgrade Backbone: ? => 1.2.3 (STORY)
      • Upgrade Backbone.Paginator: 0.8.1 => 2.0.2 (STORY)
      • Upgrade Underscore: 1.4.4 => 1.8.3 (STORY)
      • Upgrade RequireJS: 2.1.8 => 2.1.15 (STORY)
      • Update RequireJS Text: 2.0.14 => 2.0.14 (STORY)
    • Introduce gulp
      • this doesn't seem necessary immediately
      • paver commands already in place cover all the requirements
    • Complete the merging of the pagination components (STORY)
  • Update cookiecutter with front end standards (EPIC)
    • Can we use Yeoman generators? (http://yeoman.io/)
    • Use npm to install both libraries (STORY)
    • Add standard linting (STORY)
      • JSHint
      • JSCS
      • Maybe we should switch now to ESLint?
    • Add gulp (STORY)
      • Define the standard set of tasks that will be included
        • sass
        • testing (Karma)
        • code coverage
        • doc
        • linting
    • Introduce Babel?
    • Introduce WebPack?
    • How do you document your JavaScript APIs?
    • Define the directory structure (STORY)
    • Define versioning best practices (STORY)
    • Does it matter that edx-platform won't use many of these standards, e.g. Karma, gulp? No
  • Create first UI Toolkit public release (UITK-15)
    • Create documentation
      • Generate API documentation
        • Talk to doc team again
        • Where should it be hosted? ReadTheDocs?
      • Generate example documentation
        • To be included in the pattern library (or not?)
    • Determine the legal requirements, if any, e.g. what license to use
    • Bump the version number to 1.0
    • Send announcement email
  • Create first public release of the UX Platform Library
    • Bump the version number to 1.0
  • Ongoing maintenance
    • The goal is to have no dedicated team
    • All UI developers at edX and in the community should be empowered to update it as needed
      • New components should be added to the Toolkit in preference to living within a particular repo
      • API and pattern documentation should be added
    • Document the best practices and processes to be used (STORY)
      • Already have good linting (JSHint, JSCS)
      • Use the cookiecutter for new IDAs
      • HTML should be as defined in the pattern library
      • New components should be added as a pattern to the library first
      • JS doc
      • i18n
      • Security, i.e. cross-site scripting
      • Accessibility
    • Define process for introducing new patterns (STORY)
      • How can they be requested?
      • How are they vetted for appropriateness for a library versus roll-your-own?
      • Follow the best practices from above
    • Create a pull request template to cover these (STORY)
  • Programs IDA
    • Alasdair just added gulp for local development

JIRA Working Board - https://openedx.atlassian.net/secure/RapidBoard.jspa?rapidView=206

Milestones

  • FedX Team Milestones:
    • Milestone 1: transition UXPL ownership to engineering
      • design, build and publish a new pattern
      • document the steps involved
    • Milestone 2: use UX Pattern Library in edx-platform
      • update Open Web Certs to use the real Pattern Library (and remove the copy)
      • add an edX theme to demonstrate comprehensive theming
    • Milestone 3: use UI Toolkit in edx-platform
      • publish UI Toolkit an an npm package
      • update edx-platform to npm install the package
      • update edx-platform to use pagination collection from the UI Toolkit
    • Milestone 4: public release of Pattern Library
      • update to version 1.0.0
      • developer documentation
      • implement test page that uses the Pattern Library
    • Milestone 5: public release of UI Toolkit
      • update to version 1.0.0
      • documentation
      • create edx-platform test page that uses the UI Toolkit
    • Milestone 6: support for new IDAs
      • implement cookiecutter support to generate a skeleton IDA following best practices
      • document best practices and processes for using all the libraries

FedX Roadmap

StatusDateSprintNotesResources
(tick)1/14 - 1/28a-Ha
  • Spin up the FedX team
    • Work from a FedX backlog
    • Document everything in a FedX wiki
  • Start milestone 1: UXPL fully transitioned to engineering team
    • Braindump from Brian Talbot
    • Start developing the alert pattern
  • a-Ha retro
  • Andy as FedX lead
  • Dennis for UXPL transition
(tick)1/28 - 2/11Blondie
  • Complete milestone 1: UXPL fully transitioned to engineering team
    • Document processes on the wiki
    • Complete the alert pattern
    • Publish a new version
  • Complete milestone 2: UXPL available for use in edx-platform
    • Upgrade to libsass to support Sass generation
    • Upgrade Open edX web certs to use pattern library
  • Blondie retro
  • Andy as FedX lead
  • Dennis to complete documentation of UXPL process (until his vacation)
(tick)2/11 - 2/25Chvrches
  • Start milestone 3: use UI Toolkit in edx-platform
    • Publish UI Toolkit as an npm package
    • Start upgrading JavaScript libraries
  • Chvrches retro
  • Andy as FedX lead (on vacation 16-19)
  • Christina to help with edx-platform library upgrades (on vacation 18-19).
  • Dan to help with edx-platform library upgrades.
(lightbulb)2/25 - 3/10Deadmau5
  • Continue milestone 3: use UI Toolkit in edx-platform
    • Continue upgrading JavaScript libraries
    • Develop manual test plan for production upgrade
    • Integrate UI Toolkit into Pattern Library doc
  • Develop documentation plan
  • Andy as FedX lead
  • Lahore team to help with platform JavaScript upgrades.
 3/10 - 3/24Eurythmics
  • Continue milestone 3: use UI Toolkit in edx-platform
    • Continue upgrading JavaScript libraries
  • Start milestone 4: public release of Pattern Library
    • Create edx-platform test page that uses the Pattern Library
    • Complete in-progress patterns (disclosure and dropdown)
    • Update Developer Guide with new FED section
    • Update http://ux.edx.org to have a home page and more guidance
  • Andy as FedX lead
  • Brian Jacobel to join FedX team full time (on vacation 14-18).
  • Alasdair to help with UI Toolkit completion and documentation.
  • Lahore team to help with platform JavaScript upgrades.
  • Peter as documentation resource.
 3/24 - 4/7Funkadelic
  • Complete milestone 3: use UI Toolkit in edx-platform
    • Complete upgrading JavaScript libraries
    • Update edx-platform to use pagination collection from the UI Toolkit
  • Complete milestone 4: public release of Pattern Library
    • Peter to do a technical edit and revision of ux.edx.org
    • Document new pattern lifecycle
    • Publish version 1.0.0
    • Communicate to the community
  • Start milestone 5: public release of UI Toolkit
    • Update edx-platform test page to use the UI Toolkit
    • Peter to start UI Toolkit developer guide section
    • Auto-generate UI Toolkit API documentation
  • Complete milestone 5 and 6. Public release of Pattern Library and UI Toolkit available.
  • Andy as FedX lead
  • Brian Jacobel full time on FedX.
  • Lahore team to help with platform JavaScript upgrades.
  • Alasdair to help with UI Toolkit completion and documentation.
  • Peter as documentation resource.
 4/7 - 4/21Gorillaz
  • Complete milestone 5: public release of UI Toolkit
    • Peter to complete initial release of UI Toolkit developer guide
    • Publish version 1.0.0
    • Communicate to the community
  • Complete milestone 6: support for new IDAs
    • Document the processes for creating a new IDA
    • Update the cookiecutter app to support JavaScript libraries
  • Andy as FedX lead
  • Brian Jacobel full time on FedX.
  • Peter as documentation resource.
 4/21 - 5/5HAIM
  • Overflow sprint depending upon velocity
  • Andy as FedX lead
  • Brian Jacobel full time on FedX.
  • Peter as documentation resource.

Future Work

Once the FedX initiative has completed, there is still a lot of ongoing front end work to be considered. This work will be spread around the development teams, and includes at least the following:

  • Solutions for new white labels  - Solutions to own this work now
    • build new responsive, themable, multi-tenant versions of key LMS pages
    • logistration, home page, course listings, enrollment
    • have new views exist in parallel to existing ones
    • integrate with new comprehensive theming
    • should this all live in a new repo as a first step to the LMS living outside the platform?
  • XBlock usage
    • how to use the patterns without the grid
    • how can XBlocks use theming?
      • e.g. use the primary color for some custom section of their UI
    • RequireJS support
    • Backbone, Underscore etc
    • Pipeline/CDN support
  • edx-platform upgrades
    • Update standalone edx-platform pages
      • login/registration
      • accounts
      • learner profiles
      • teams
    • Eventually update the courseware
      • can we bring in everything from the UX Pattern Library but the grid? fonts, colors, variables etc
      • does this buy us much?
      • maybe do this as part of implementing the new navigation
      • big challenge is a strategy for XBlocks and theming etc
    • Incremental improvements
      • build new pages as new views
      • do a gradual rollout to users
      • XBlocks will need to be rendered into both old and new views
  • future patterns/components
    • complete in progress patterns
      • alerts
      • collapsible
      • drop down
      • tables
      • pagination
    • header/footer
    • bread crumbs
    • lists, cards, search results
    • form views from logistration
    • modals
    • tabs
    • marketing patterns, e.g. billboard
    • ORA workflow patterns, e.g. headers, steps, alerts/notification
    • perform an audit to see what we're missing
  • future consumers
    • migrate Analytics to Pattern Library from Bootstrap
    • migrate Drupal site
    • migrate Otto
    • migrate Programs
    • new discussion design

Open Issues 

  • how to involve community
    • email early with the goals and milestones
    • email release announcements
  • how to involve arch council
    • should we do this before emailing the community
  • need to size the effort - story points vs t-shirt sizing?
  • XBlock usage
  • pull request template
  • document process for extending both libraries
  • RequireJS vs WebPack vs Browserify vs Django Compressor
  • paver vs Gulp vs make
  • what belongs in devDependencies versus dependencies
  • No labels

3 Comments

  1. Piotr Mitros Calen Pennington Nimisha Asthagiri Gabe Mulley - this first draft of a plan touches on some of the XBlock theming questions we discussed at lunch. It would be good to get the necessary work into a backlog so that XBlock authors have a clear path forward.

  2. Andy Armstrong - Hi! As a part of the work the commerce team is doing for XSeries, Zubair AfzalAwais Qureshi and others are moving certificates into a separate 'credentials' IDA (edx-credentials). During planning the thought was that we'd be able to continue using the s3 hosted css file currently used by the course web certs. One item that was missed is the fact that the XSeries web certs needs to load font files as well as pattern library / toolkit JS to correctly render the accessible icons. For that reason, the team is looking into including the pattern library / toolkit ASAP on edx-credentials. Alasdair Swan is going to point them to the current documentation but I wanted to mention this to the (FedX? (wink) ) team so that you're aware of it! If there are any speed bumps you're aware of that you could alert Zubair & Awais to that would be great too. 

    Thanks!

    cc'ed Zachary Rockwell

    1. Thanks for the head up, Marco Morales. Our current plan is to update the web certs code in place in the edx-platform, so we'll need to do something else! FYI Brian Talbot.