Skip to content

Commit 1001e56

Browse files
drwldrwl
authored
Add guide for migrating from Annotate gem (#24)
1 parent 017301f commit 1001e56

File tree

2 files changed

+231
-5
lines changed

2 files changed

+231
-5
lines changed

‎MIGRATION_GUIDE.md

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
## Guide for migrating from Annotate to AnnotateRb
2+
### Notable differences
3+
* AnnotateRb drops support for older version of Ruby. At the time of writing, the minimum supported Ruby version is 2.7 as older versions have been end-of-life'd for sometime now.
4+
* The command line interface has been changed to make commands easier to run annotations for models and routes separately. Refer to Command line differences section for more details.
5+
* Configuration can now be done in a yml file instead of reading from ENV.
6+
* No longer reads configuration options from ENV / environment variables.
7+
* Annotate gem added 4 rake commands: `annotate_models`, `remove_annotation`, `annotate_routes`, `remove_routes` that were removed. If you use these and would like them back please open an issue.
8+
9+
----------
10+
11+
## Migration overview
12+
Annotate provided 3 ways for passing options to the gem.
13+
1. [Through the command line](#command-line-differences)
14+
2. [Using environment variables (ENV)](#passing-options-via-environment-variables)
15+
3. [Rake files that got installed](#automatic-annotations-after-running-database-migration-commands)
16+
17+
----------
18+
### Command line differences
19+
Previously, Annotate allowed you to annotate both model and route files in the same command. In an attempt to make the CLI easier to use, they are now separate. The following output is what you see when running annotaterb without any options.
20+
21+
**Note: most of the options are similar with the following differences:**
22+
* `--models` has been removed, to annotate models use `annotaterb models [options]` instead
23+
* `-r`, `--routes` has been removed, to annotate routes use `annotaterb routes [options]` instead
24+
25+
If you notice any differences please [report an issue](https://github.com/drwl/annotaterb/issues/new) or [submit a pull request](https://github.com/drwl/annotaterb/pulls) to update this document.
26+
27+
```sh
28+
$ bundle exec annotaterb
29+
30+
Usage: annotaterb [command] [options]
31+
32+
Commands:
33+
models [options]
34+
routes [options]
35+
help
36+
version
37+
38+
Options:
39+
-v, --version Display the version..
40+
-h, --help You're looking at it.
41+
42+
Annotate model options:
43+
Usage: annotaterb models [options]
44+
45+
-a, --active-admin Annotate active_admin models
46+
--show-migration Include the migration version number in the annotation
47+
-k, --show-foreign-keys List the table's foreign key
48+
...
49+
50+
Annotate routes options:
51+
Usage: annotaterb routes [options]
52+
53+
--ignore-routes REGEX don't annotate routes that match a given REGEX (i.e., `annotate -I '(mobile|resque|pghero)'`
54+
...
55+
Command options:
56+
Additional options that work for annotating models and routes
57+
58+
--additional-file-patterns path1,path2,path3
59+
Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)
60+
-d, --delete Remove annotations from all model files or the routes.rb file
61+
--model-dir dir Annotate model files stored in dir rather than app/models, separate multiple dirs with commas
62+
--root-dir dir Annotate files stored within root dir projects, separate multiple dirs with commas
63+
--ignore-model-subdirects Ignore subdirectories of the models directory
64+
--sort Sort columns alphabetically, rather than in creation order
65+
--classified-sort Sort columns alphabetically, but first goes id, then the rest columns, then the timestamp columns and then the association columns
66+
-R, --require path Additional file to require before loading models, may be used multiple times
67+
-e [tests,fixtures,factories,serializers],
68+
--exclude Do not annotate fixtures, test files, factories, and/or serializers
69+
...
70+
```
71+
72+
----------
73+
74+
### Passing options via Environment Variables
75+
Annotate also reads options from ENV. For example, this command line argument `ANNOTATE_SKIP_ON_DB_MIGRATE=1 rake db:migrate` would affect Annotate's behavior.
76+
77+
The reading from ENV / environment variables has **been removed** in favor of reading configuration from `.annotaterb.yml` file in your Rails project root.
78+
79+
```yml
80+
# .annotaterb.yml
81+
82+
position: after
83+
```
84+
85+
This change was done to reduce complexity in configuration and make the gem easier to maintain.
86+
87+
**Note: `.annotaterb.yml` is optional.** In its, AnnotateRb will use command line arguments and then the defaults. The defaults are implemented in `AnnotateRb::Options`.
88+
89+
----------
90+
91+
### Automatic annotations after running database migration commands
92+
The old Annotate gem came with a generator that installed the following Rake file(s) into your Rails project.
93+
94+
```
95+
lib/tasks/auto_annotate_models.rake
96+
```
97+
98+
This rake task loaded other Annotate code that hooked into the Rails database migration rake tasks to automatically annotate after running database related tasks.
99+
100+
**Before removing the file, make note of your favored defaults.** For example, you might see the following:
101+
102+
```ruby
103+
Annotate.set_defaults(
104+
'active_admin' => 'false',
105+
'additional_file_patterns' => [],
106+
'routes' => 'false',
107+
'models' => 'true',
108+
...
109+
```
110+
111+
These key-value pairs would go in the yml file mentioned above. After removing the rake task, run:
112+
113+
```sh
114+
$ bin/rails g annotate_rb:install
115+
```
116+
117+
to install AnnotateRb's equivalent file into your Rails project.
118+
119+
#### Default .annotaterb.yml
120+
If your `lib/tasks/auto_annotate_models.rake` uses the default settings from Annotate:
121+
```ruby
122+
Annotate.set_defaults(
123+
'active_admin' => 'false',
124+
'additional_file_patterns' => [],
125+
'routes' => 'false',
126+
'models' => 'true',
127+
'position_in_routes' => 'before',
128+
'position_in_class' => 'before',
129+
'position_in_test' => 'before',
130+
'position_in_fixture' => 'before',
131+
'position_in_factory' => 'before',
132+
'position_in_serializer' => 'before',
133+
'show_check_constraints' => 'false',
134+
'show_foreign_keys' => 'true',
135+
'show_complete_foreign_keys' => 'false',
136+
'show_indexes' => 'true',
137+
'simple_indexes' => 'false',
138+
'model_dir' => 'app/models',
139+
'root_dir' => '',
140+
'include_version' => 'false',
141+
'require' => '',
142+
'exclude_tests' => 'false',
143+
'exclude_fixtures' => 'false',
144+
'exclude_factories' => 'false',
145+
'exclude_serializers' => 'false',
146+
'exclude_scaffolds' => 'true',
147+
'exclude_controllers' => 'true',
148+
'exclude_helpers' => 'true',
149+
'exclude_sti_subclasses' => 'false',
150+
'ignore_model_sub_dir' => 'false',
151+
'ignore_columns' => nil,
152+
'ignore_routes' => nil,
153+
'ignore_unknown_models' => 'false',
154+
'hide_limit_column_types' => '<%= AnnotateModels::NO_LIMIT_COL_TYPES.join(",") %>',
155+
'hide_default_column_types' => '<%= AnnotateModels::NO_DEFAULT_COL_TYPES.join(",") %>',
156+
'skip_on_db_migrate' => 'false',
157+
'format_bare' => 'true',
158+
'format_rdoc' => 'false',
159+
'format_yard' => 'false',
160+
'format_markdown' => 'false',
161+
'sort' => 'false',
162+
'force' => 'false',
163+
'frozen' => 'false',
164+
'classified_sort' => 'true',
165+
'trace' => 'false',
166+
'wrapper_open' => nil,
167+
'wrapper_close' => nil,
168+
'with_comment' => 'true'
169+
)
170+
```
171+
172+
And you want to keep those defaults, you can use the following `.annotaterb.yml` file.
173+
174+
**Note: there were bugs in Annotate that may have lead to options not actually being used for some of the `exclude_*` options. If you experience different behavior despite using the same defaults then this may be why.**
175+
176+
### Example .annotaterb.yml that uses same Annotate defaults
177+
178+
```yaml
179+
# .annotaterb.yml
180+
181+
active_admin: false
182+
additional_file_patterns: [ ]
183+
routes: false
184+
models: true
185+
position_in_routes: before
186+
position_in_class: before
187+
position_in_test: before
188+
position_in_fixture: before
189+
position_in_factory: before
190+
position_in_serializer: before
191+
show_check_constraints: false
192+
show_foreign_keys: true
193+
show_complete_foreign_keys: false
194+
show_indexes: true
195+
simple_indexes: false
196+
model_dir: [ 'app/models' ]
197+
root_dir: [ '' ]
198+
include_version: false
199+
require: [ ]
200+
exclude_tests: false
201+
exclude_fixtures: false
202+
exclude_factories: false
203+
exclude_serializers: false
204+
exclude_scaffolds: true
205+
exclude_controllers: true
206+
exclude_helpers: true
207+
exclude_sti_subclasses: false
208+
ignore_model_sub_dir: false
209+
ignore_columns:
210+
ignore_routes:
211+
ignore_unknown_models: false
212+
hide_limit_column_types: ''
213+
hide_default_column_types: ''
214+
skip_on_db_migrate: false
215+
format_bare: true
216+
format_rdoc: false
217+
format_yard: false
218+
format_markdown: false
219+
sort: false
220+
force: false
221+
frozen: false
222+
classified_sort: true
223+
trace: false
224+
wrapper_open:
225+
wrapper_close:
226+
with_comment: true
227+
```

‎README.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,7 @@ $ bin/rails g annotate_rb:install
6060
This will copy a rake task into your Rails project's `lib/tasks` directory that will hook into the Rails project rake tasks, automatically running AnnotateRb after database migration rake tasks.
6161

6262
## Migrating from the annotate gem
63-
The old [annotate gem](https://github.com/ctran/annotate_models) relied on environment variables and hardcoded values in rake files for configuration. AnnotateRb is different. It reads from an optional configuration yml file and options from the CLI to function.
64-
65-
* Remove the following files `lib/tasks/annotate_models.rake`, `lib/tasks/annotate_models_migrate.rake`, `lib/tasks/annotate_routes.rake`.
66-
* Run the generator install command above.
63+
Refer to the [migration guide](MIGRATION_GUIDE.md).
6764

6865
## Usage
6966

@@ -160,7 +157,9 @@ Previously in the [Annotate](https://github.com/ctran/annotate_models) you could
160157
position: after
161158
```
162159
163-
Annotaterb reads first from the configuration file, if it exists, then merges it with any options passed into the CLI.
160+
Annotaterb reads first from the configuration file, if it exists, then merges it with any options passed into the CLI.
161+
162+
For further details visit the [section in the migration guide](MIGRATION_GUIDE.md#automatic-annotations-after-running-database-migration-commands).
164163
165164
### How to skip annotating a particular model
166165
If you want to always skip annotations on a particular model, add this string

0 commit comments

Comments
 (0)