Created
June 27, 2012 22:13
-
-
Save stayce/bc907bb189ad6e698351 to your computer and use it in GitHub Desktop.
first draft UIT readme
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| UI Toolkit -- A Toolkit for Wildfire Developers | |
| ==================================== | |
| ## DESCRIPTION | |
| UI Toolkit (UIT) is a Rails Engine packaged as a Ruby Gem that contains code for WF Developers to help keep apps looking good across the WF social suite and its plugins. UIT includes layout partials, component partials, styles, and javascript as well as external library dependencies. | |
| UIT also includes a sandbox app which provides documentation and working demos of how to use the included UI components. | |
| Approximately 15 applications use UIT to provide look and feel, with a community of around 5 developers and product owners. It affects the users of 13,000 customers, reaching thousands of marketers. | |
| Note: This document refers to the latest 5-1-Alpha branch, unless otherwise noted. | |
| #### RELEASES | |
| Further information on each release can be found on the [wiki](https://github.com/wildfireapp/ui-toolkit/wiki) | |
| * 1.0, 2.0 - Rails 2, 3.0 | |
| * 3.0 - Rails 3.0, 3.1 | |
| * 4.0 - Rails 3.0, 3.1, Bump jQuery UI version | |
| * 5.0 - Rails 3.2.x, Replaced many helpers and plugins with [Bootstrap](http://twitter.github.com/bootstrap/) | |
| * 5.1-Alpha - Rails 3.2.x, Release candidate for WF site redesign | |
| ## STYLE GUIDE | |
| UIT includes a style guide in the sandbox that ensures app developers adhere to a specific format when designing new pages and layouts. This style guide can also be found [online](http://ui-toolkit.wildfirestaging.com/ui/style_guide). | |
| ## INSTALLATION | |
| Install UIT by adding the following to your Gemfile: | |
| `gem 'ui-toolkit', :git => 'git@github.com:wildfireapp/ui-toolkit.git', :branch => '5-1-alpha'` | |
| Then use [Bundler](http://gembundler.com/) to pick up all the dependencies: | |
| $ bundle install | |
| ## RUNNING | |
| To view the UIT Sandbox App locally, simply run: | |
| $ bundle exec rackup | |
| This will start up a web server running the UI Toolkit Sandbox and you can view | |
| it in browser at http://localhost:9292 | |
| ## UPGRADING FROM PREVIOUS VERSIONS | |
| Upgrading instructions can be found on the [wiki](https://github.com/wildfireapp/ui-toolkit/wiki) | |
| UIT 5.0 includes breaking changes to helpers, plugins and methods. We've tried to document them all on the following pages: | |
| * [Configuration changes between 4.0 and 5.0](https://github.com/wildfireapp/ui-toolkit/wiki/Configuration-changes-between-4.0-and-5.0) | |
| * [Deprecated Helpers](https://github.com/wildfireapp/ui-toolkit/wiki/Deprecated-Helpers) | |
| * [Unimplemented JS Plugins and methods in v5.0](https://github.com/wildfireapp/ui-toolkit/wiki/Unimplemented-JS-Plugins-and-methods-in-v5.0) | |
| UIT 5.x uses vendor assets and helpers to facilitate development. These inclue: | |
| 1. [Simple form]([https://github.com/plataformatec/simple_form]) | |
| 1. [bootstrap 2.0](http://twitter.github.com/bootstrap/) | |
| 1. [chosen](http://harvesthq.github.com/chosen/) | |
| 1. [jquery](http://jquery.com/) | |
| ## LAYOUT PARTIALS | |
| UIT provides 2 layout partials (thin and default) and 6 component partials which are included in the default layout partial. Apps can render the ui-toolkit partials directly, or choose to create copies of certain layouts to modify locally. | |
| #### Default layout partial | |
| * Includes 6 partials: head, sidebar, header, footer, externals, and application-info | |
| * Located at /app/views/ui-toolkit/_layout.html.haml | |
| #### Thin layout partial | |
| * A basic layout with a different header and no sidebar, fully documented [here](http://ui-toolkit.wildfirestaging.com/ui/thin_layout). | |
| * Includes 5 partials: head, header-thin, footer, externals, and application-info | |
| * Located at /app/views/ui-toolkit/_layout_thin.html.haml | |
| ## COMPONENT PARTIALS | |
| #### Head | |
| * Located in /app/views/ui-toolkit/_head.html.haml | |
| * Contains meta-content for the HTML <head> section. | |
| #### Sidebar | |
| * Located in /app/views/ui-toolkit/_sidebar.html.haml | |
| * Contains content for the sidebar navigation. | |
| * Sidebars have many UIT components which are fully documented [here](http://ui-toolkit.wildfirestaging.com/ui/side_panel). | |
| * The sidebar partial is always rendered in the default layout, but never used in the thin layout. | |
| * There is code in the sidebar to handle the account switching. Users should not have to modify this code. | |
| #### Header | |
| * Header | |
| * Located in /app/views/ui-toolkit/_header.html.haml | |
| * Contains content for the header section including sidebar toggle button, notificaitons, and page title. | |
| * Rendered in the default layout, but not the thin-layout. | |
| * Header-Thin | |
| * Located in /app/views/ui-toolkit/_header.html.haml | |
| * Contains content for the header section including sidebar toggle button, notificaitons, and page title. | |
| * Rendered in the default layout, but not the thin-layout. | |
| #### Externals | |
| * Located in /app/views/ui-toolkit/_externals.html.haml | |
| * Renders 3 additional partials located in /app/views/ui-toolkit/externals directory. These are google analytics, snapabug, and zendesk and could alternatively be rendered individually. | |
| ## DEPENDENCIES | |
| * Located in the [Gemfile](https://github.com/wildfireapp/ui-toolkit/blob/5-1-alpha/Gemfile) and the [Gemspec](https://github.com/wildfireapp/ui-toolkit/blob/5-1-alpha/ui-toolkit.gemspec) | |
| ## CONTRIBUTE | |
| If you'd like to contribute to UI Toolkit, start by creating a new branch from the latest appropriate integration branch on GitHub: | |
| (currently 5-1-alpha) https://github.com/wildfireapp/ui-toolkit/tree/5-1-alpha | |
| The best way to get your changes merged back in is as follows: | |
| 1. Add your feature to the [Suggestions and Discussions Wiki](https://github.com/wildfireapp/ui-toolkit/wiki/Suggestions-&-Discussions) so other users can discuss | |
| 1. Do you work on your topic branch, push that topic branch up to the latest repository. | |
| 1. Use your topic branch in your Gemfile until you receive notice from the UIT team. | |
| 1. Add tests and make sure everything still passes by running `bundle exec rspec spec` | |
| 1. If you are adding new functionality, document it in this README or on the [Wiki](https://github.com/wildfireapp/ui-toolkit/wiki/Suggestions-&-Discussions) | |
| 1. Push the branch up to GitHub | |
| 1. Send a pull request to the github/ui-toolkit project maintainer (Baked Goods at present), who will review your patch, and consider the release process. | |
| 1. If you have two or more changes, it is generally better to use a topic per change. You should then create an integration branch, into which you can merge multiple topics. | |
| 1. Integration topics should be named by the project and possibly current integration or feature branch that will be using the new features. If Account Management is working on a “multiuser” branch for example, then the name of the integration branch would be account_management-multiuser. This will prevent clobbering and make the branch usage clear to the project owner and anyone else, especially when they come to clean up the branches. | |
| ## RELEASING | |
| 1. Bump the version in ui-toolkit.gemspec | |
| 1. * (UI Toolkit follows the rules of [Semantic Versioning](http://semver.org/) ) | |
| 1. Bundle install | |
| 1. Commit change | |
| 1. Re-run specs to ensure everything is sound `rspec spec` | |
| 1. Create a tag for that version | |
| 1. git push && git push –tags | |
| 1. Notify the team (bakedgoods@wildfireapp.com) of the new version | |
| ## COPYRIGHT | |
| Copyright © 2010-2012 Wildfire Interactive, inc. See LICENSE for details. |
Author
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
UI Toolkit -- A Toolkit for Wildfire Developers
DESCRIPTION
UI Toolkit (UIT) is a Rails Engine packaged as a Ruby Gem that contains code for WF Developers to help keep apps looking good across the WF social suite and its plugins. UIT includes layout partials, component partials, styles, and javascript as well as external library dependencies.
UIT also includes a sandbox app which provides documentation and working demos of how to use the included UI components.
Approximately 15 applications use UIT to provide look and feel, with a community of around 5 developers and product owners. It affects the users of 13,000 customers, reaching thousands of marketers.
Note: This document refers to the latest 5-1-Alpha branch, unless otherwise noted.
RELEASES
Further information on each release can be found on the wiki
STYLE GUIDE
UIT includes a style guide in the sandbox that ensures app developers adhere to a specific format when designing new pages and layouts. This style guide can also be found online.
INSTALLATION
Install UIT by adding the following to your Gemfile:
Then use Bundler to pick up all the dependencies:
RUNNING
To view the UIT Sandbox App locally, simply run:
This will start up a web server running the UI Toolkit Sandbox and you can view
it in browser at http://localhost:9292
UPGRADING FROM PREVIOUS VERSIONS
Upgrading instructions can be found on the wiki
UIT 5.0 includes breaking changes to helpers, plugins and methods. We've tried to document them all on the following pages:
UIT 5.x uses vendor assets and helpers to facilitate development. These inclue:
LAYOUT PARTIALS
UIT provides 2 layout partials (thin and default) and 6 component partials which are included in the default layout partial. Apps can render the ui-toolkit partials directly, or choose to create copies of certain layouts to modify locally.
Default layout partial
Thin layout partial
COMPONENT PARTIALS
Head
Sidebar
Header
Externals
DEPENDENCIES
CONTRIBUTE
If you'd like to contribute to UI Toolkit, start by creating a new branch from the latest appropriate integration branch on GitHub:
(currently 5-1-alpha) https://github.com/wildfireapp/ui-toolkit/tree/5-1-alpha
The best way to get your changes merged back in is as follows:
bundle exec rspec specRELEASING
rspec specCOPYRIGHT
Copyright © 2010-2012 Wildfire Interactive, inc. See LICENSE for details.