annotate 2.5.0 → 2.6.0.beta2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9cf1dc6bc654533120158f1a4e03caffd4dcb429
+  data.tar.gz: 12c3f503657c5d96ae02675a47ea5420956918ca
+SHA512:
+  metadata.gz: 69f28f89810d03767192f46583b550a34dac95332fd7d5fe545e57d5405fa5e97664966d2b0700a67eb6a56096a4085db1d1d557773d7947789c017ed7ac3de1
+  data.tar.gz: d613cad136a5a6941bb33563c777d835a9dfa8b9db7f1c0d9851afbe4976b9763ad279e30515d48fe3304e4241fa9af3c463a94244da13fad6117abf406c20a3

data/{History.txt → CHANGELOG.rdoc}

@@ -1,3 +1,51 @@
+== 2.6.0.beta2
+
+* support for composite_primary_keys (garysweaver)
+* bug fix for annotate_one_file (vlado)
+
+== 2.6.0.beta1
+
+* It's now possible to use Annotate in standalone ActiveRecord (non-Rails)
+  projects again.
+* Adding note that Markdown is actually MultiMarkdown, and recommending the use
+  of the `kramdown` engine for parsing it.
+* Improved Markdown formatting considerably.
+* Bugfix: Needed to use inline-code tag for column and table names, otherwise
+  underscores would cause havok with the formatting.
+* Bugfix: Markdown syntax was incorrect (can't have trailing spaces before the
+  closing marker for an emphasis tag).
+* Bugfix: Remove-annotations wasn't properly finding test/spec files, and
+  wasn't even looking for FactoryGirl factories under the new naming
+  convention.
+* Bugfix: Load the Rakefile from the current directory, not the first Rakefile
+  in our load path.
+* Added support for new FactoryGirl naming convention.
+* Fix behavior of route annotations in newer versions of Rake that don't spit
+  out the CWD as their first line of output.
+* Overhauled integration testing system to be much easier to work with, better
+  compartmentalized, and so forth -- at the cost that you must be using RVM to
+  utilize it.  (It'll spit out appropriate pending messages if you don't.)
+  Also includes a mode for "tinkering" by hand with a scenario, and won't let
+  you run it through rspect if the repo is in a dirty state.  Added appropriate
+  rake tasks to help with all of this.
+* Routes can now be appended, pre-pended, or removed -- and do sane things in
+  all cases.
+* Expose all `position_*` variables as CLI params.
+* Make `ENV ['position']` work as a default for all the `ENV ['position_*']`
+  variables.
+* Make rake tasks more resilient to unusual circumstances / code loading
+  behavior.
+* Resolve annotate vs. annotate_models ambiguity once and for all by settling
+  on `annotate_models` _and_ `annotate_routes`.  This avoids a name collision
+  with RMagick while not needlessly overloading the term.
+* Fixed that schema kept prepending additional newlines
+* Updates to make annotate smarter about when to touch a model
+* Recognize column+type, and don't change a file unless the column+type
+  combination of the new schema are different than that of the old (i.e., don't
+  regenerate if columns happen to be in a different order. That's just how life
+  is sometimes)
+* Change annotate to use options hash instead of ENV.
+
 == 2.5.0
 
 * Works better with Rails 3
@@ -6,17 +54,23 @@
 * Recognize column+type, and don't change a file unless the column+type combination of the new schema are different than that of the old (i.e., don't regenerate if columns happen to be in a different order. That's just how life is sometimes.)
 * Grab old specification even if it has \r\n as line endings rather than pure \ns
 * Various warning and specification fixes
-* Fix "no such file to load -- annotate/annotate_models (MissingSourceFile)" error (require statements in tasks now use full path to lib files)
-* warn about macros, to mitigate when we're included during a production run, not just a rakefile run -- possibly at the expense of too much noise
+* Fix "no such file to load -- annotate/annotate_models (MissingSourceFile)"
+  error (require statements in tasks now use full path to lib files)
+* warn about macros, to mitigate when we're included during a production run,
+  not just a rakefile run -- possibly at the expense of too much noise
 * Adding rake as a runtime dependency
-* If the schema is already in the model file, it will be replaced into the same location.  If it didn't previously exist, it'll be placed according to the "position", as before.
-* Allow task loading from Rakefile for gems (plugin installation already auto-detects).
+* If the schema is already in the model file, it will be replaced into the same
+  location.  If it didn't previously exist, it'll be placed according to the
+  "position", as before.
+* Allow task loading from Rakefile for gems (plugin installation already
+  auto-detects).
 * Add skip_on_db_migrate option as well for people that don't want it
 * Fix options parsing to convert strings to proper booleans
 * Add support for Fabrication fabricators
 * Leave magic encoding comment intact
 * Fix issue #14 - RuntimeError: Already memoized
 * Count a model as 'annotated' if any of its tests/fixtures are annotated
+* Support FactoryGirl
 * Support :change migrations (Rails 3.1)
 * Allow models with non-standard capitalization
 * Widen type column so we can handle longtexts with chopping things off.
@@ -27,7 +81,7 @@
   '# -*- SkipSchemaAnnotations' anywhere in the file.
 * Don't show column limits for integer and boolean types.
 * Add sorting for columns and indexes. (Helpful for out-of-order migration
-  execution, but use --no-sort if you don't want this.)
+  execution.  Use --sort if you want this.)
 * Annotate unit tests in subfolders.
 * Add generator to install rakefile that automatically annotates on db:migrate.
 * Correct Gemfile to clarify which environments need which gems.
@@ -38,6 +92,7 @@
   non-standard capitalization.
   Note that this still requires that the inflector be configured to understand
   the special case.
+* Shore up test cases a bit.
 * Merge against many of the older branches on Github whose functionality is
   already reflected to reduce confusion about what is and is not implemented
   here.
@@ -72,7 +127,8 @@
 
 == 2.4.0 2009-12-13
 
-* Incorporated lots of patches from the Github community, including support for Blueprints fixtures
+* Incorporated lots of patches from the Github community, including support for
+  Blueprints fixtures
 * Several bug fixes
 
 == 2.1 2009-10-18

data/README.rdoc

@@ -1,6 +1,10 @@
 == Annotate (aka AnnotateModels)
 
-Add a comment summarizing the current schema to the top or bottom of each of your...
+IMPORTANT:  If you're upgrading from a previous version, including 2.5.0,
+re-run the generator task!
+
+Add a comment summarizing the current schema to the top or bottom of each of
+your...
 
 - ActiveRecord models
 - Fixture files
@@ -9,7 +13,7 @@ Add a comment summarizing the current schema to the top or bottom of each of you
 - Machinist blueprints
 - Fabrication fabricators
 - Thoughtbot's factory_girl factories, i.e. the (spec|test)/factories/<model>_factory.rb files
-- routes.rb file
+- routes.rb file (for Rails projects)
 
 The schema comment looks like this:
 
@@ -28,7 +32,8 @@ The schema comment looks like this:
       belongs_to :product
      . . .
 
-It also annotates geometrical columns, geom type and srid, when using SpatialAdapter or PostgisAdapter:
+It also annotates geometrical columns, geom type and srid, when using
+`SpatialAdapter` or `PostgisAdapter`:
 
    # == Schema Info
    #
@@ -37,9 +42,11 @@ It also annotates geometrical columns, geom type and srid, when using SpatialAda
    #  local           :geometry        point, 4326
    #  path            :geometry        line_string, 4326
 
-Also, if you pass the -r option, it'll annotate routes.rb with the output of "rake routes".
+Also, if you pass the -r option, it'll annotate routes.rb with the output of
+`rake routes`.
+
 
-== INSTALL
+== Install
 
 Into Gemfile from rubygems.org:
 
@@ -49,7 +56,7 @@ Into Gemfile from Github:
 
     gem 'annotate', :git => 'git://github.com/ctran/annotate_models.git'
 
-Into environment gems From rubygems.org:
+Into environment gems from rubygems.org:
 
     gem install annotate
 
@@ -60,50 +67,111 @@ Into environment gems from Github checkout:
     rake build
     gem install pkg/annotate-*.gem
 
-== USAGE
+
+== Usage
 
 (If you used the Gemfile install, prefix the below commands with `bundle exec`.)
 
-To annotate all your models, tests, fixtures, etc.:
+=== Usage in Rails
 
-  cd /path/to/app
-  annotate
+To annotate all your models, tests, fixtures, and factories:
 
-To annotate your models and tests:
+    cd /path/to/app
+    annotate
 
-  annotate --exclude fixtures
+To annotate just your models, tests, and factories:
+
+    annotate --exclude fixtures
 
 To annotate just your models:
 
-  annotate --exclude tests,fixtures
+    annotate --exclude tests,fixtures,factories
 
 To annotate routes.rb:
 
-  annotate -r
+    annotate --routes
+
+To remove model/test/fixture/factory annotations:
+
+    annotate --delete
+
+To remove routes.rb annotations:
+
+    annotate --routes --delete
+
 
-To remove annotations:
+== Configuration
 
-  annotate -d
 
-To automatically annotate after running 'rake db:migrate', ensure you've added
-annotate_models to your Rails project's Gemfile, and run this:
+=== Usage Outside of Rails
 
-  rails g annotate_models:install
+Everything above applies, except that --routes is not meaningful, and you will
+probably need to explicitly set one or more `--require` option(s), and/or one
+or more `--model-dir` options to inform annotate about the structure of your
+project and help it bootstrap and load the relevant code.
 
-This will produce a .rake file that will ensure annotation happens after
-migration (but only in development mode), and provide configuration options
-you can use to tailor the output.
+
+
+== Configuration
 
 If you want to always skip annotations on a particular model, add this string
 anywhere in the file:
 
-  # -*- SkipSchemaAnnotations
+    # -*- SkipSchemaAnnotations
+
+To generate a configuration file (in the form of a `.rake` file), to set
+default options:
+
+    rails g annotate:install
+
+Edit this file to control things like output format, where annotations are
+added (top or bottom of file), and in which artifacts.
+
+
+=== Configuration in Rails
+
+To generate a configuration file (in the form of a `.rake` file), to set
+default options:
+
+    rails g annotate:install
 
-== OPTIONS
+Edit this file to control things like output format, where annotations are
+added (top or bottom of file), and in which artifacts.
+== Rails Integration
+
+By default, once you've generated a configuration file, annotate will be
+executed whenever you run `rake db:migrate` (but only in development mode).
+If you want to disable this behavior permanently, edit the `.rake` file and
+change:
+
+    'skip_on_db_migrate'   => "false",
+
+To:
+
+    'skip_on_db_migrate'   => "try",
+
+If you want to run `rake db:migrate` as a one-off without running annotate,
+you can do so with a simple environment variable, instead of editing the
+`.rake` file:
+
+    skip_on_db_migrate=1 rake db:migrate
+
+
+== Options
 
     Usage: annotate [options] [model_file]*
-        -d, --delete                     Remove annotations from all model files
-        -p, --position [before|after]    Place the annotations at the top (before) or the bottom (after) of the model file
+        -d, --delete                     Remove annotations from all model files or the routes.rb file
+        -p, --position [before|after]    Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/routes file(s)
+            --pc, --position-in-class [before|after]
+                                         Place the annotations at the top (before) or the bottom (after) of the model file
+            --pf, --position-in-factory [before|after]
+                                         Place the annotations at the top (before) or the bottom (after) of any factory files
+            --px, --position-in-fixture [before|after]
+                                         Place the annotations at the top (before) or the bottom (after) of any fixture files
+            --pt, --position-in-test [before|after]
+                                         Place the annotations at the top (before) or the bottom (after) of any test files
+            --pr, --position-in-routes [before|after]
+                                         Place the annotations at the top (before) or the bottom (after) of the routes.rb file
         -r, --routes                     Annotate routes.rb with the output of 'rake routes'
         -v, --version                    Show the current version of this gem
         -m, --show-migration             Include the migration version number in the annotation
@@ -112,31 +180,51 @@ anywhere in the file:
             --model-dir dir              Annotate model files stored in dir rather than app/models
             --ignore-model-subdirects    Ignore subdirectories of the models directory
             --sort                       Sort columns alphabetically, rather than in creation order
-        -R, --require path               Additional files to require before loading models
-        -e, --exclude [tests,fixtures]   Do not annotate fixtures, test files, or both
+        -R, --require path               Additional file to require before loading models, may be used multiple times
+        -e [tests,fixtures,factories],   Do not annotate fixtures, test files, and/or factories
+            --exclude
         -f [bare|rdoc|markdown],         Render Schema Infomation as plain/RDoc/Markdown
             --format
             --force                      Force new annotations even if there are no changes.
             --trace                      If unable to annotate a file, print the full stack trace, not just the exception message.
 
 
-== SORTING
+== Sorting
 
-By default, columns will be sorted in database order (i.e. the order in which migrations were run).
+By default, columns will be sorted in database order (i.e. the order in which
+migrations were run).
 
 If you prefer to sort alphabetically so that the results of
-annotation are consistent regardless of what order migrations are executed in, use  --sort.
+annotation are consistent regardless of what order migrations are executed in,
+use  --sort.
+
+
+== Markdown
+
+The format produced is actually MultiMarkdown, making use of the syntax
+extension for tables.  It's recommended you use `kramdown` as your parser if
+you want to use this format.  If you're using `yard` to generate documentation,
+specify a format of markdown with `kramdown` as the provider by adding this to
+your `.yardopts` file:
+
+    --markup markdown
+    --markup-provider kramdown
+
+Be sure to add this to your `Gemfile` as well:
+
+    gem 'kramdown', :groups => [:development], :require => false
+
 
 == WARNING
 
-Note that this code will blow away the initial/final comment
-block in your models if it looks like it was previously added
-by annotate models, so you don't want to add additional text
-to an automatically created comment block.
+Note that this code will blow away the initial/final comment block in your
+models if it looks like it was previously added by this gem, so you don't want
+to add additional text to an automatically created comment block.
 
 BACK UP YOUR MODELS BEFORE USING THIS TOOL!
 
-== LINKS
+
+== Links
 
 - Factory Girl: http://github.com/thoughtbot/factory_girl
 - Object Daddy: http://github.com/flogic/object_daddy
@@ -145,11 +233,13 @@ BACK UP YOUR MODELS BEFORE USING THIS TOOL!
 - SpatialAdapter: http://github.com/pdeffendol/spatial_adapter
 - PostgisAdapter: http://github.com/nofxx/postgis_adapter
 
-== LICENSE:
+
+== License
 
 Released under the same license as Ruby. No Support. No Warranty.
 
-== AUTHORS:
+
+== Authors
 
 - Original code by: Dave Thomas -- Pragmatic Programmers, LLC <http://agilewebdevelopment.com/plugins/annotate_models>
 - Overhauled by: Alex Chaffee <http://alexch.github.com> alex@stinky.com
@@ -181,4 +271,4 @@ With help from:
 - Dmitry Lihachev
 - qichunren
 
-and many others that I may have missed to add.
+and many others that I may have forgotten to add.

data/TODO.rdoc

@@ -0,0 +1,12 @@
+== TODO
+
+- clean up history
+- change default position back to "top" for all annotations
+- add "top" and "bottom" as synonyms for "before" and "after"
+- change 'exclude' to 'only' (double negatives are not unconfusing)
+
+== TODO (proposed)
+
+- push two identical gems, named 'annotate' and 'annotate_models'
+- supply two binaries, named 'annotate' and 'annotate_models', since there's already a unix tool named 'annotate'
+- test EVERYTHING

data/annotate.gemspec

@@ -0,0 +1,38 @@
+# This file is auto-generated!
+# DO NOT EDIT THIS FILE DIRECTLY!
+# Instead, edit the Rakefile and run 'rake gems:gemspec'.# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "annotate"
+  s.version = "2.6.0.beta2"
+
+  s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Cuong Tran", "Alex Chaffee", "Marcos Piccinini", "Turadg Aleahmad", "Jon Frisby"]
+  s.date = "2013-06-21"
+  s.description = "Annotates Rails/ActiveRecord Models, routes, fixtures, and others based on the database schema."
+  s.email = ["alex@stinky.com", "ctran@pragmaquest.com", "x@nofxx.com", "turadg@aleahmad.net", "jon@cloudability.com"]
+  s.executables = ["annotate"]
+  s.extra_rdoc_files = ["README.rdoc", "CHANGELOG.rdoc", "TODO.rdoc"]
+  s.files = ["CHANGELOG.rdoc", "README.rdoc", "TODO.rdoc", "annotate.gemspec", "bin/annotate", "lib/annotate.rb", "lib/annotate/active_record_patch.rb", "lib/annotate/annotate_models.rb", "lib/annotate/annotate_routes.rb", "lib/annotate/tasks.rb", "lib/annotate/version.rb", "lib/generators/annotate/USAGE", "lib/generators/annotate/install_generator.rb", "lib/generators/annotate/templates/auto_annotate_models.rake", "lib/tasks/annotate_models.rake", "lib/tasks/annotate_routes.rake", "tasks/migrate.rake"]
+  s.homepage = "http://github.com/ctran/annotate_models"
+  s.licenses = ["Ruby"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = "annotate"
+  s.rubygems_version = "2.0.3"
+  s.summary = "Annotates Rails Models, routes, fixtures, and others based on the database schema."
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rake>, [">= 0.8.7"])
+      s.add_runtime_dependency(%q<activerecord>, [">= 2.3.0"])
+    else
+      s.add_dependency(%q<rake>, [">= 0.8.7"])
+      s.add_dependency(%q<activerecord>, [">= 2.3.0"])
+    end
+  else
+    s.add_dependency(%q<rake>, [">= 0.8.7"])
+    s.add_dependency(%q<activerecord>, [">= 2.3.0"])
+  end
+end

data/bin/annotate

@@ -1,34 +1,78 @@
 #!/usr/bin/env ruby
-require 'optparse'
-require 'rake/dsl_definition'
-require 'rake'
+require 'rubygems'
 begin
-  require "annotate"
-rescue LoadError
-  here = File.expand_path(File.dirname __FILE__)
-  $:<< "#{here}/../lib"
-  require "annotate"
+  require 'bundler'
+  Bundler.setup
+rescue Exception => e
 end
 
-task = :annotate_models
+here = File.expand_path(File.dirname __FILE__)
+$:<< "#{here}/../lib"
 
+require 'optparse'
+require 'annotate'
+Annotate.bootstrap_rake
+
+target = {
+  :klass => AnnotateModels,
+  :task => :do_annotations,
+}
+has_set_position = {}
 OptionParser.new do |opts|
   opts.banner = "Usage: annotate [options] [model_file]*"
 
   opts.on('-d', '--delete',
-          "Remove annotations from all model files") do
-    task = :remove_annotation
+          "Remove annotations from all model files or the routes.rb file") do
+
+    target[:task] = :remove_annotations
   end
 
-  ENV['position'] = 'before' # hack: make sure default position is "before"
   opts.on('-p', '--position [before|after]', ['before', 'after'],
-          "Place the annotations at the top (before) or the bottom (after) of the model file") do |p|
+          "Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/routes file(s)") do |p|
     ENV['position'] = p
+    [
+      'position_in_class','position_in_factory','position_in_fixture','position_in_test', 'position_in_routes'
+    ].each do |key|
+      ENV[key] = p unless(has_set_position[key])
+    end
+  end
+
+  opts.on('--pc', '--position-in-class [before|after]', ['before', 'after'],
+          "Place the annotations at the top (before) or the bottom (after) of the model file") do |p|
+    ENV['position_in_class'] = p
+    has_set_position['position_in_class'] = true
+  end
+
+  opts.on('--pf', '--position-in-factory [before|after]', ['before', 'after'],
+          "Place the annotations at the top (before) or the bottom (after) of any factory files") do |p|
+    ENV['position_in_factory'] = p
+    has_set_position['position_in_factory'] = true
+  end
+
+  opts.on('--px', '--position-in-fixture [before|after]', ['before', 'after'],
+          "Place the annotations at the top (before) or the bottom (after) of any fixture files") do |p|
+    ENV['position_in_fixture'] = p
+    has_set_position['position_in_fixture'] = true
+  end
+
+  opts.on('--pt', '--position-in-test [before|after]', ['before', 'after'],
+          "Place the annotations at the top (before) or the bottom (after) of any test files") do |p|
+    ENV['position_in_test'] = p
+    has_set_position['position_in_test'] = true
+  end
+
+  opts.on('--pr', '--position-in-routes [before|after]', ['before', 'after'],
+          "Place the annotations at the top (before) or the bottom (after) of the routes.rb file") do |p|
+    ENV['position_in_test'] = p
+    has_set_position['position_in_routes'] = true
   end
 
   opts.on('-r', '--routes',
           "Annotate routes.rb with the output of 'rake routes'") do
-    task = :annotate_routes
+    target = {
+      :klass => AnnotateRoutes,
+      :task => :do_annotations
+    }
   end
 
   opts.on('-v', '--version',
@@ -67,15 +111,15 @@ OptionParser.new do |opts|
   end
 
   opts.on('-R', '--require path',
-          "Additional files to require before loading models") do |path|
-    if ENV['require']
+          "Additional file to require before loading models, may be used multiple times") do |path|
+    if !ENV['require'].blank?
       ENV['require'] = ENV['require'] + ",#{path}"
     else
       ENV['require'] = path
     end
-  end\
+  end
 
-  opts.on('-e', '--exclude [tests,fixtures]', Array, "Do not annotate fixtures, test files, or both") do |exclusions|
+  opts.on('-e', '--exclude [tests,fixtures,factories]', ['tests','fixtures','factories'], "Do not annotate fixtures, test files, and/or factories") do |exclusions|
     exclusions.each { |exclusion| ENV["exclude_#{exclusion}"] = "yes" }
   end
 
@@ -90,13 +134,9 @@ OptionParser.new do |opts|
   opts.on('--trace', 'If unable to annotate a file, print the full stack trace, not just the exception message.') do |value|
     ENV['trace'] = 'yes'
   end
-
-
 end.parse!
 
-ENV['is_cli'] = '1'
-if Annotate.load_tasks
-  Rake::Task[task].invoke
-else
-  STDERR.puts "Can't find Rakefile. Are we in a Rails folder?"
-end
+
+options=Annotate.setup_options({ :is_rake => !ENV['is_rake'].blank? })
+Annotate.eager_load(options)
+target[:klass].send(target[:task], options)