annotate 2.7.5 → 3.2.0

data/{README.rdoc → README.md}

@@ -1,15 +1,14 @@
-== Annotate (aka AnnotateModels)
+## Annotate (aka AnnotateModels)
 
-{<img src="https://badge.fury.io/rb/annotate.svg" alt="Gem Version" />}[http://badge.fury.io/rb/annotate]
-{<img src="https://img.shields.io/gem/dt/annotate.svg?style=flat" />}[https://rubygems.org/gems/annotate]
-{<img src="https://travis-ci.org/ctran/annotate_models.svg?branch=develop" />}[https://travis-ci.org/ctran/annotate_models]
-{<img src="https://coveralls.io/repos/ctran/annotate_models/badge.svg?branch=develop" />}[https://coveralls.io/r/ctran/annotate_models?branch=develop]
-{<img src="https://codeclimate.com/github/ctran/annotate_models/badges/gpa.svg" />}[https://codeclimate.com/github/ctran/annotate_models]
-{<img src="http://inch-ci.org/github/ctran/annotate_models.svg?branch=develop" alt="Inline docs" />}[http://inch-ci.org/github/ctran/annotate_models]
-{<img src="https://gemnasium.com/ctran/annotate_models.png" />}[https://gemnasium.com/ctran/annotate_models]
+[![Gem Version](https://badge.fury.io/rb/annotate.svg)](http://badge.fury.io/rb/annotate)
+[![Downloads count](https://img.shields.io/gem/dt/annotate.svg?style=flat)](https://rubygems.org/gems/annotate)
+[![Build status](https://travis-ci.org/ctran/annotate_models.svg?branch=develop)](https://travis-ci.org/ctran/annotate_models)
+[![CI Status](https://github.com/ctran/annotate_models/workflows/CI/badge.svg)](https://github.com/ctran/annotate_models/actions?workflow=CI)
+[![Coveralls](https://coveralls.io/repos/ctran/annotate_models/badge.svg?branch=develop)](https://coveralls.io/r/ctran/annotate_models?branch=develop)
+[![Maintenability](https://codeclimate.com/github/ctran/annotate_models/badges/gpa.svg)](https://codeclimate.com/github/ctran/annotate_models)
+[![Inline docs](http://inch-ci.org/github/ctran/annotate_models.svg?branch=develop)](http://inch-ci.org/github/ctran/annotate_models)
 
-Add a comment summarizing the current schema to the top or bottom of each of
-your...
+Add a comment summarizing the current schema to the top or bottom of each of your...
 
 - ActiveRecord models
 - Fixture files
@@ -17,53 +16,85 @@ your...
 - Object Daddy exemplars
 - Machinist blueprints
 - Fabrication fabricators
-- Thoughtbot's factory_bot factories, i.e. the (spec|test)/factories/<model>_factory.rb files
-- routes.rb file (for Rails projects)
+- Thoughtbot's factory_bot factories, i.e. the `(spec|test)/factories/<model>_factory.rb` files
+- `routes.rb` file (for Rails projects)
+
 
 The schema comment looks like this:
 
-   # == Schema Info
-   #
-   # Table name: line_items
-   #
-   #  id                  :integer(11)    not null, primary key
-   #  quantity            :integer(11)    not null
-   #  product_id          :integer(11)    not null
-   #  unit_price          :float
-   #  order_id            :integer(11)
-   #
+```ruby
+# == Schema Info
+#
+# Table name: line_items
+#
+#  id                  :integer(11)    not null, primary key
+#  quantity            :integer(11)    not null
+#  product_id          :integer(11)    not null
+#  unit_price          :float
+#  order_id            :integer(11)
+#
+
+class LineItem < ActiveRecord::Base
+  belongs_to :product
+  . . .
+```
+
+It also annotates geometrical columns, `geom` type and `srid`,
+when using `SpatialAdapter`, `PostgisAdapter` or `PostGISAdapter`:
+
+```ruby
+# == Schema Info
+#
+# Table name: trips
+#
+#  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`.
 
-    class LineItem < ActiveRecord::Base
-      belongs_to :product
-     . . .
 
-It also annotates geometrical columns, geom type and srid, when using
-+SpatialAdapter+, +PostgisAdapter+ or +PostGISAdapter+:
+## Upgrading to 3.X and annotate models not working?
 
-   # == Schema Info
-   #
-   # Table name: trips
-   #
-   #  local           :geometry        point, 4326
-   #  path            :geometry        line_string, 4326
+In versions 2.7.X the annotate gem defaulted to annotating models if no arguments were passed in.
+The annotate gem by default would not allow for routes and models to be annotated together.
+A [change was added in #647](https://github.com/ctran/annotate_models/pull/647).
+You [can read more here](https://github.com/ctran/annotate_models/issues/663).
 
-Also, if you pass the -r option, it'll annotate routes.rb with the output of
-<code>rake routes</code>.
+There are a few ways of fixing this:
 
+- If using CLI explicitly pass in models flag using `--models`
 
-== Install
+OR
+
+a) Running `rails g annotate:install` will overwrite your defaults with the annotating `models` option set to `'true'`.
+
+b) In `lib/tasks/auto_annotate_models.rake` add the `models` key-value option:
+
+```ruby
+    Annotate.set_defaults(
+      ...
+      'models'                      => 'true',
+      ...
+```
+
+## Install
 
 Into Gemfile from rubygems.org:
 
-    group :development do
-      gem 'annotate'
-    end
+```ruby
+group :development do
+  gem 'annotate'
+end
+```
 
 Into Gemfile from Github:
 
-    group :development do
-      gem 'annotate', git: 'https://github.com/ctran/annotate_models.git'
-    end
+```ruby
+group :development do
+  gem 'annotate', git: 'https://github.com/ctran/annotate_models.git'
+end
+```
 
 Into environment gems from rubygems.org:
 
@@ -73,15 +104,14 @@ Into environment gems from Github checkout:
 
     git clone https://github.com/ctran/annotate_models.git annotate_models
     cd annotate_models
-    rake build
-    gem install pkg/annotate-*.gem
-
+    rake gem
+    gem install dist/annotate-*.gem
 
-== Usage
+## Usage
 
-(If you used the Gemfile install, prefix the below commands with <code>bundle exec</code>.)
+(If you used the Gemfile install, prefix the below commands with `bundle exec`.)
 
-=== Usage in Rails
+### Usage in Rails
 
 To annotate all your models, tests, fixtures, and factories:
 
@@ -90,11 +120,11 @@ To annotate all your models, tests, fixtures, and factories:
 
 To annotate just your models, tests, and factories:
 
-    annotate --exclude fixtures
+    annotate --models --exclude fixtures
 
 To annotate just your models:
 
-    annotate --exclude tests,fixtures,factories,serializers
+    annotate --models
 
 To annotate routes.rb:
 
@@ -108,26 +138,28 @@ To remove routes.rb annotations:
 
     annotate --routes --delete
 
-To automatically annotate every time you run <code>db:migrate</code>, either run <code>rails g annotate:install</code> or add +Annotate.load_tasks+ to your `Rakefile`. See the {configuration in Rails}[link:README.rdoc#configuration-in-rails] section for more info.
+To automatically annotate every time you run `db:migrate`,
+either run `rails g annotate:install`
+or add `Annotate.load_tasks` to your `Rakefile`.
 
-=== Usage Outside of Rails
+See the [configuration in Rails](#configuration-in-rails) section for more info.
 
-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.
+### Usage Outside of Rails
 
+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.
 
-== Configuration
+## Configuration
 
 If you want to always skip annotations on a particular model, add this string
 anywhere in the file:
 
     # -*- SkipSchemaAnnotations
 
-=== Configuration in Rails
+### Configuration in Rails
 
-To generate a configuration file (in the form of a +.rake+ file), to set
+To generate a configuration file (in the form of a `.rake` file), to set
 default options:
 
     rails g annotate:install
@@ -135,7 +167,7 @@ default options:
 Edit this file to control things like output format, where annotations are
 added (top or bottom of file), and in which artifacts.
 
-The generated rakefile +lib/tasks/auto_annotate_models.rake+ also contains
+The generated rakefile `lib/tasks/auto_annotate_models.rake` also contains
 `Annotate.load_tasks`. This adds a few rake tasks which duplicate command-line
 functionality:
 
@@ -144,26 +176,30 @@ functionality:
     rake remove_annotation                        # Remove schema information from model and fixture files
 
 By default, once you've generated a configuration file, annotate will be
-executed whenever you run <code>rake db:migrate</code> (but only in development mode).
-If you want to disable this behavior permanently, edit the +.rake+ file and
-change:
+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:
 
+```ruby
     'skip_on_db_migrate'   => 'false',
+```
 
 To:
 
+```ruby
     'skip_on_db_migrate'   => 'true',
+```
 
-If you want to run <code>rake db:migrate</code> as a one-off without running annotate,
+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:
+`.rake` file:
 
     ANNOTATE_SKIP_ON_DB_MIGRATE=1 rake db:migrate
 
-
-== Options
+## Options
 
     Usage: annotate [options] [model_file]*
+            --additional-file-patterns   Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)
         -d, --delete                     Remove annotations from all model files or the routes.rb file
         -p [before|top|after|bottom],    Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)
             --position
@@ -184,6 +220,7 @@ you can do so with a simple environment variable, instead of editing the
             --wo, --wrapper-open STR     Annotation wrapper opening.
             --wc, --wrapper-close STR    Annotation wrapper closing
         -r, --routes                     Annotate routes.rb with the output of 'rake routes'
+            --models                     Annotate ActiveRecord models
         -a, --active-admin               Annotate active_admin models
         -v, --version                    Show the current version of this gem
         -m, --show-migration             Include the migration version number in the annotation
@@ -200,78 +237,95 @@ you can do so with a simple environment variable, instead of editing the
         -R, --require path               Additional file to require before loading models, may be used multiple times
         -e [tests,fixtures,factories,serializers],
             --exclude                    Do not annotate fixtures, test files, factories, and/or serializers
-        -f [bare|rdoc|markdown],         Render Schema Infomation as plain/RDoc/Markdown
+        -f [bare|rdoc|yard|markdown],    Render Schema Infomation as plain/RDoc/YARD/Markdown
             --format
             --force                      Force new annotations even if there are no changes.
             --frozen                     Do not allow to change annotations. Exits non-zero if there are going to be changes to files.
             --timestamp                  Include timestamp in (routes) annotation
             --trace                      If unable to annotate a file, print the full stack trace, not just the exception message.
-        -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`
-            --ignore-routes REGEX        don't annotate routes that match a given REGEX (i.e., `annotate -I '(mobile|resque|pghero)'`
+        -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (e.g. `annotate -I '^(id|updated_at|created_at)'`)
+            --ignore-routes REGEX        don't annotate routes that match a given REGEX (e.g. `annotate -I '(mobile|resque|pghero)'`)_
             --hide-limit-column-types VALUES
-                                         don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)
+                                         don't show limit for given column types, separated by commas (e.g. `integer,boolean,text`)
             --hide-default-column-types VALUES
-                                         don't show default for given column types, separated by commas (i.e., `json,jsonb,hstore`)
+                                         don't show default for given column types, separated by commas (e.g. `json,jsonb,hstore`)
             --ignore-unknown-models      don't display warnings for bad model files
             --with-comment               include database comments in model annotations
 
+### Option: `additional_file_patterns`
+
+CLI: `--additional-file-patterns`<br>
+Ruby: `:additional_file_patterns`
+
+Provide additional paths for the gem to annotate.  These paths can include
+globs. It is recommended to use absolute paths.  Here are some examples:
+
+*   `/app/lib/decorates/%MODEL_NAME%/*.rb`
+*   `/app/lib/forms/%PLURALIZED_MODEL_NAME%/**/*.rb`
+*   `/app/lib/forms/%TABLE_NAME%/*.rb`
+
 
+The appropriate model will be inferred using the `%*%` syntax, annotating any
+matching files. It works with existing filename resolutions (options for which
+can be found in the `resolve_filename` method of `annotate_models.rb`).
 
-== Sorting
+When using in a Rails config, you can use the following:
+
+`File.join(Rails.application.root,
+'app/lib/forms/%PLURALIZED_MODEL_NAME%/***/**.rb')`
+
+## Sorting
 
 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+.
+If you prefer to sort alphabetically so that the results of annotation are
+consistent regardless of what order migrations are executed in, use `--sort`.
 
-
-== Markdown
+## 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:
+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
+Be sure to add this to your `Gemfile` as well:
 
+    gem 'kramdown', groups => [:development], require => false
 
-== WARNING
+## WARNING
 
-<b>Don't add text after an automatically-created comment block.</b> This tool
+**Don't add text after an automatically-created comment block.** This tool
 will blow away the initial/final comment block in your models if it looks like
 it was previously added by this gem.
 
-Be sure to check the changes that this tool makes! If you are using Git,
-you may simply check your project's status after running +annotate+:
+Be sure to check the changes that this tool makes! If you are using Git, you
+may simply check your project's status after running `annotate`:
 
     $ git status
 
 If you are not using a VCS (like Git, Subversion or similar), please tread
 extra carefully, and consider using one.
 
-== Links
+## Links
 
-- Factory Bot: http://github.com/thoughtbot/factory_bot
-- Object Daddy: http://github.com/flogic/object_daddy
-- Machinist: http://github.com/notahat/machinist
-- Fabrication: http://github.com/paulelliott/fabrication
-- SpatialAdapter: http://github.com/pdeffendol/spatial_adapter
-- PostgisAdapter: http://github.com/nofxx/postgis_adapter
-- PostGISAdapter: https://github.com/dazuma/activerecord-postgis-adapter
+*   Factory Bot: http://github.com/thoughtbot/factory_bot
+*   Object Daddy: http://github.com/flogic/object_daddy
+*   Machinist: http://github.com/notahat/machinist
+*   Fabrication: http://github.com/paulelliott/fabrication
+*   SpatialAdapter: http://github.com/pdeffendol/spatial_adapter
+*   PostgisAdapter: http://github.com/nofxx/postgis_adapter
+*   PostGISAdapter: https://github.com/dazuma/activerecord-postgis-adapter
 
 
-== License
+## License
 
 Released under the same license as Ruby. No Support. No Warranty.
 
-== Authors
+## Authors
 
-{See AUTHORS.rdoc}[link:AUTHORS.rdoc].
+[See AUTHORS.md](AUTHORS.md).

data/RELEASE.md

@@ -0,0 +1,19 @@
+## Prerequisite 
+
+- Install "git-flow" (`brew install git-flow`)
+- Install "bump" gem (`gem install bump`)
+
+
+## Perform a release
+
+- `git flow release start <release>`
+- Update the `CHANGELOG.md` file
+- `bump current`
+- `bump patch`
+- `rm -rf dist`
+- `rake spec`
+- `rake gem`
+- `git flow release finish <release>`
+
+- `rake gem:publish`
+

data/annotate.gemspec

@@ -7,42 +7,26 @@ Gem::Specification.new do |s|
   s.name = 'annotate'
   s.version = Annotate.version
 
-  s.required_ruby_version = '>= 2.2.0'
+  s.required_ruby_version = '>= 2.4.0'
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
   s.authors = ['Alex Chaffee', 'Cuong Tran', 'Marcos Piccinini', 'Turadg Aleahmad', 'Jon Frisby']
   s.description = 'Annotates Rails/ActiveRecord Models, routes, fixtures, and others based on the database schema.'
   s.email = ['alex@stinky.com', 'cuong.tran@gmail.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 = [
-    'AUTHORS.rdoc',
-    'CHANGELOG.rdoc',
-    'LICENSE.txt',
-    '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',
-    'lib/tasks/annotate_models_migrate.rake'
-  ]
-  s.homepage = 'http://github.com/ctran/annotate_models'
+  s.extra_rdoc_files = ['README.md', 'CHANGELOG.md']
+  s.files = `git ls-files -z LICENSE.txt *.md *.gemspec bin lib`.split("\x0")
+  s.homepage = 'https://github.com/ctran/annotate_models'
   s.licenses = ['Ruby']
   s.require_paths = ['lib']
-  s.rubyforge_project = 'annotate'
   s.rubygems_version = '2.1.11'
   s.summary = 'Annotates Rails Models, routes, fixtures, and others based on the database schema.'
 
   s.specification_version = 4 if s.respond_to? :specification_version
-  s.add_runtime_dependency(%q<rake>, ['>= 10.4', '< 13.0'])
-  s.add_runtime_dependency(%q<activerecord>, ['>= 3.2', '< 7.0'])
+  s.add_runtime_dependency(%q<rake>, '>= 10.4', '< 14.0')
+  s.add_runtime_dependency(%q<activerecord>, ['>= 3.2', '< 8.0'])
+
+  s.metadata = {
+    "bug_tracker_uri" => "https://github.com/ctran/annotate_models/issues/",
+    "source_code_uri" => "https://github.com/ctran/annotate_models.git"
+  }
 end