README.md in torba-0.3.0 vs README.md in torba-0.3.1

- old
+ new

@@ -19,41 +19,39 @@ [Released version](http://rubydoc.info/gems/torba/0.3.0) ## Why -De facto approach, i.e. wrapping JS and CSS libraries in a gem, requires from a -maintainer to constantly track changes in upstream repository. Even more, if the -maintainer stops using this gem itself, it will eventually become abandoned. -Many libraries still have no gem wrappers. +De facto approach, i.e. wrapping JS and CSS libraries in a gem, requires a +maintainer to constantly track changes in an upstream repository. Even more so, if a gem +maintainer stops using that specific library, the gem will eventually become abandoned. +Additionally, many libraries still have no gem wrappers. -Among other alternatives: +Other alternatives: -* [rails-assets][rails-assets] project relies on Bower *and* it is quite complex, -* [bower-rails][bower-rails] project relies on Bower. +* [rails-assets][rails-assets] relies on Bower *and* it is quite complex, +* [bower-rails][bower-rails] relies on Bower, see below for why this can be an issue. Problems with the Bower: -* it is not a part of Ruby ecosystem, -* frontend JS libraries are usually standalone (except for jQuery dependency), so there's - no need for complex Bundler-like solution with tree-dependency resolution, -* often we can't use optimistic version constraints, because JS community still doesn't - fully grasp the idea of [Semver][semver]. By specifying strict versions we use Bower - as a complex facade for functionality that could be done by curl. +* it is not a part of the Ruby ecosystem, +* frontend JS libraries are usually standalone (except for a potential jQuery dependency), so there's + no need for a complex Bundler-like solution with tree-dependency resolution, +* often we can't use optimistic version constraints, because the JavaScript community does not consistenly apply the principles of [Semver][semver]. By specifying strict versions we use Bower as a complex facade for functionality that could be accomplished with curl. ## External dependencies * curl * unzip * gzip * tar ## Design limitations -* Torba doesn't do any version dependency resolution, it's up to you to specify correct version of +* Torba doesn't do any version dependency resolution, it's up to you to specify the correct version of each asset package, -* Torba doesn't do any builds, use remote sources with pre-built assets. +* Torba doesn't do any builds, you should use remote sources with pre-built assets. ## Installation Add this line to your application's Gemfile and run `bundle`: @@ -181,20 +179,20 @@ When you run `torba pack` the following happens: 1. All remote sources are cached locally. -2. Archives are unpacked with top level directory removed. This is done for good cause it -usually contains package version, e.g. "react-0.13.2", and you don't want to reference versions +2. Archives are unpacked with top level directory removed. This is done for good because it +usually contains the package version in the name, e.g. "react-0.13.2", and you don't want to have to reference versions inside your application code (except Torbafile). 3. Remote source's content is copied as is to the `Torba.home_path` location with **package name used as a namespace**. - This is also done for good in order to avoid name collisions (since many JS projects can have -assets with the same names and all packages are placed into shared Sprockets' virtual filesystem). -The downside is that you have to use namespace in each require directive, which can lead to + This is also done for good reason in order to avoid name collisions (since many JS projects can have +assets with the same names and all packages are placed into Sprockets' shared virtual filesystem). +The downside is that you have to use namespaces in each require directive, which can lead to duplication: ```javascript // application.js //= require 'underscore/underscore' @@ -209,19 +207,19 @@ 4. Stylesheets (if any) are converted to ".css.erb" with "asset_path" helpers used in "url(...)" statements. ### :import option -Copying whole remote source's content has one disadvantage of using remote source specific paths in your -require/import directives. For example, if an archive contains file in "dist/css" directory, you'll have +Copying whole remote source's content has the disadvantage of using remote source specific paths in your +require/import directives. For example, if an archive contains files in the "dist/css" directory, you'll have to mention it: ```css /* application.css */ @import 'lightslider/dist/css/lightslider'; ``` -To mitigate this you can cherry-pick files from the source via "import" option, for example: +To mitigate this you can cherry-pick files from the source via the "import" option, for example: ``` gh_release "lightslider", source: "sachinchoolur/lightslider", tag: "1.1.2", import: %w[ dist/css/lightslider.css ]