initial commit

.github/CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing
+
+Thanks for your interest in PaperTrail!
+
+Ask usage questions on Stack Overflow:
+https://stackoverflow.com/tags/paper-trail-gem
+
+**Please do not use github issues to ask usage questions.**
+
+On github, we appreciate bug reports, feature suggestions, and pull requests.
+
+## Reporting Bugs
+
+Please use our [bug report template][1].
+
+## Reporting Security Vulnerabilities
+
+Please email jared@jaredbeck.com, batkinz@gmail.com
+
+We will respond as soon as we can. Thank you for responsibly disclosing
+security vulnerabilities.
+
+## Development
+
+Install gems with `bundle exec appraisal install`.
+
+Testing is a little awkward because the test suite:
+
+1. Supports multiple versions of rails
+1. Contains a "dummy" rails app with three databases (test, foo, and bar)
+1. Supports three different RDBMS': sqlite, mysql, and postgres
+
+### Test sqlite, AR 4.2
+
+```
+# Create the appropriate database config. file
+rm spec/dummy_app/config/database.yml
+DB=sqlite bundle exec rake prepare
+
+# If this is the first test run ever, create databases.
+# We can't use `appraisal` inside the dummy app, so we must set `BUNDLE_GEMFILE`.
+# See spec/dummy_app/config/boot.rb for a complete explanation.
+cd spec/dummy_app
+export BUNDLE_GEMFILE=../../gemfiles/ar_4.2.gemfile
+RAILS_ENV=test bundle exec rake db:setup
+RAILS_ENV=foo bundle exec rake db:setup
+RAILS_ENV=bar bundle exec rake db:setup
+unset BUNDLE_GEMFILE
+cd ../..
+
+# Run tests
+DB=sqlite bundle exec appraisal ar-4.2 rake
+
+# Run a single test
+DB=sqlite bundle exec appraisal ar-4.2 rspec spec/paper_trail/serializers/json_spec.rb
+```
+
+### Test sqlite, AR 5
+
+```
+# Create the appropriate database config. file
+rm spec/dummy_app/config/database.yml
+DB=sqlite bundle exec rake prepare
+
+# If this is the first test run ever, create databases.
+# We can't use `appraisal` inside the dummy app, so we must set `BUNDLE_GEMFILE`.
+# See spec/dummy_app/config/boot.rb for a complete explanation.
+cd spec/dummy_app
+export BUNDLE_GEMFILE=../../gemfiles/ar_5.0.gemfile
+RAILS_ENV=test bundle exec rake db:environment:set db:setup
+RAILS_ENV=foo bundle exec rake db:environment:set db:setup
+RAILS_ENV=bar bundle exec rake db:environment:set db:setup
+unset BUNDLE_GEMFILE
+cd ../..
+
+# Run tests
+DB=sqlite bundle exec appraisal ar-5.0 rake
+```
+
+### Test mysql, AR 5
+
+```
+# Create the appropriate database config. file
+rm spec/dummy_app/config/database.yml
+DB=mysql bundle exec rake prepare
+
+# If this is the first test run ever, create databases.
+# We can't use `appraisal` inside the dummy app, so we must set `BUNDLE_GEMFILE`.
+# See spec/dummy_app/config/boot.rb for a complete explanation.
+cd spec/dummy_app
+export BUNDLE_GEMFILE=../../gemfiles/ar_5.0.gemfile
+RAILS_ENV=test bundle exec rake db:environment:set db:setup
+RAILS_ENV=foo bundle exec rake db:environment:set db:setup
+RAILS_ENV=bar bundle exec rake db:environment:set db:setup
+unset BUNDLE_GEMFILE
+cd ../..
+
+# Run tests
+DB=mysql bundle exec appraisal ar-5.0 rake
+```
+
+### Test postgres, AR 5
+
+```
+# Create the appropriate database config. file
+rm spec/dummy_app/config/database.yml
+DB=postgres bundle exec rake prepare
+
+# If this is the first test run ever, create databases.
+# Unlike mysql, use create/migrate instead of setup.
+# We can't use `appraisal` inside the dummy app, so we must set `BUNDLE_GEMFILE`.
+# See spec/dummy_app/config/boot.rb for a complete explanation.
+cd spec/dummy_app
+export BUNDLE_GEMFILE=../../gemfiles/ar_5.0.gemfile
+DB=postgres RAILS_ENV=test bundle exec rake db:environment:set db:drop db:create db:migrate
+DB=postgres RAILS_ENV=foo bundle exec rake db:environment:set db:drop db:create db:migrate
+DB=postgres RAILS_ENV=bar bundle exec rake db:environment:set db:drop db:create db:migrate
+unset BUNDLE_GEMFILE
+cd ../..
+
+# Run tests
+DB=postgres bundle exec rake
+DB=postgres bundle exec appraisal ar-5.0 rake
+```
+
+## Editing the migration
+
+After editing `spec/dummy_app/db/migrate/20110208155312_set_up_test_tables.rb` ..
+
+```
+cd spec/dummy_app
+export BUNDLE_GEMFILE=../../gemfiles/ar_5.1.gemfile
+RAILS_ENV=test bundle exec rake db:environment:set db:drop db:create db:migrate
+RAILS_ENV=foo bundle exec rake db:environment:set db:drop db:create db:migrate
+RAILS_ENV=bar bundle exec rake db:environment:set db:drop db:create db:migrate
+unset BUNDLE_GEMFILE
+cd ../..
+```
+
+Don't forget to commit changes to `schema.rb`.
+
+## Documentation
+
+### Generate the Table of Contents
+
+```
+yarn global add markdown-toc
+markdown-toc -i --maxdepth 3 --bullets='-' README.md
+```
+
+## Releases
+
+1. Set the version in lib/paper_trail/version_number.rb
+  - Set PRE to nil unless it's a pre-release (beta, rc, etc.)
+1. In the changelog,
+  - Replace "Unreleased" with the date in iso-8601 format
+  - Add a new "Unreleased" section
+1. In the readme, update references to version number, including
+  - documentation links table
+  - compatability table (major versions only)
+1. Commit
+1. git tag -a -m "v5.0.0" "v5.0.0" # or whatever number
+1. git push --tags origin 5-stable # or whatever branch
+1. gem build paper_trail.gemspec
+1. gem push paper_trail-5.0.0.gem
+
+[1]: https://github.com/airblade/paper_trail/blob/master/doc/bug_report_template.rb

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,13 @@
+Thanks for your interest in PaperTrail! Our volunteers' time is limited, so we
+can only respond on GitHub to *bug reports* and *feature requests*.
+
+Please ask *usage questions* on StackOverflow:
+https://stackoverflow.com/tags/paper-trail-gem
+
+Bug reports must use this template:
+https://github.com/airblade/paper_trail/blob/master/doc/bug_report_template.rb
+
+For other questions, please see our contributing guide:
+https://github.com/airblade/paper_trail/blob/master/.github/CONTRIBUTING.md
+
+Thanks for your contribution!

.gitignore

@@ -0,0 +1,27 @@
+*.gem
+*.sqlite3-journal
+.bundle
+.byebug_history
+.idea
+.rbenv-gemsets
+.rbenv-version
+.rspec_results
+.ruby-gemset
+.ruby-version
+.rvmrc
+.tags
+.tags_sorted_by_file
+Gemfile.lock
+NOTES
+coverage
+gemfiles/*.lock
+pkg/*
+spec/dummy/
+spec/dummy_app/config/database.yml
+spec/dummy_app/db/*.sqlite3
+spec/dummy_app/log/*
+spec/dummy_app/tmp/*
+test/debug.log
+test/paper_trail_plugin.sqlite3.db
+vendor/*
+.DS_Store

.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

.rubocop.yml

@@ -0,0 +1,148 @@
+require:
+  - rubocop-rspec
+
+inherit_from: .rubocop_todo.yml
+
+# Please:
+#
+# - Comment any deviations from the Ruby Style Guide
+# - Alphabetize cops
+# - Only include permanent config; temporary goes in .rubocop_todo.yml
+
+AllCops:
+  Exclude:
+    - gemfiles/vendor/bundle/**/* # This dir only shows up on travis ¯\_(ツ)_/¯
+    - spec/dummy_app/db/schema.rb # Generated, out of our control
+
+  # Set to lowest supported version
+  TargetRubyVersion: 2.3
+
+Layout/AlignParameters:
+  Enabled: false
+  EnforcedStyle: with_first_parameter
+
+Layout/DotPosition:
+  EnforcedStyle: leading
+
+Layout/IndentHeredoc:
+  Exclude:
+    - paper_trail.gemspec
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+# Use exactly one space on each side of an operator. Do not align operators
+# because it makes the code harder to edit, and makes lines unnecessarily long.
+Layout/SpaceAroundOperators:
+  AllowForAlignment: false
+
+# Migrations often contain long up/down methods, and extracting smaller methods
+# from these is of questionable value.
+Metrics/AbcSize:
+  Exclude:
+    - 'spec/dummy_app/db/migrate/*'
+
+# Not a useful metric compared to, e.g. `AbcSize`.
+Metrics/BlockLength:
+  Enabled: false
+
+# Not a useful metric compared to, e.g. `AbcSize`.
+Metrics/ClassLength:
+  Enabled: false
+
+# The Ruby Style Guide recommends to "Limit lines to 80 characters."
+# (https://github.com/bbatsov/ruby-style-guide#80-character-limits)
+# but 100 is also reasonable.
+Metrics/LineLength:
+  Max: 120
+  Severity: warning
+
+# The number of lines in a method is not a useful metric compared to `AbcSize`.
+# It's common to have very long methods (> 50 lines) which are quite simple. For
+# example, a method that returns a long string with only a few interpolations.
+Metrics/MethodLength:
+  Enabled: false
+
+# Not a useful metric compared to, e.g. `AbcSize`.
+Metrics/ModuleLength:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - Appraisals
+
+# It is a decades-old convention to use EOS as a heredoc delimiter. There is
+# not enough value in changinge this convention. SQL should still be used as
+# a delimiter when appropriate.
+Naming/HeredocDelimiterNaming:
+  Enabled: false
+
+Naming/PredicateName:
+  NameWhitelist: has_paper_trail
+
+# In 0.50.0, this cop has a bug https://github.com/bbatsov/rubocop/issues/4732
+Performance/HashEachMethods:
+  Enabled: false
+
+# In an ideal world, each example has a single expectation. In the real world,
+# sometimes setup is a pain and you don't want to duplicate setup in multiple
+# examples, or make the specs more confusing with many nested `context`s, and
+# the practical thing is to have multiple expectations.
+RSpec/MultipleExpectations:
+  Enabled: true
+
+# Yes, ideally examples would be short. Is it possible to pick a limit and say,
+# "no example will ever be longer than this"? Hard to say. Sometimes they're
+# quite long.
+RSpec/ExampleLength:
+  Enabled: false
+
+# Please use semantic style, e.g. `do` when there's a side-effect, else `{}`.
+# The semantic style is too nuanced to lint, so the cop is disabled.
+Style/BlockDelimiters:
+  Enabled: false
+
+# Use double negation wherever it would otherwise be impractical to convert
+# a value to an actual boolean.
+Style/DoubleNegation:
+  Enabled: false
+
+# The decision of when to use a guard clause to improve readability is subtle,
+# and it's not clear that it can be linted. Certainly, the default
+# `MinBodyLength` of 1 can actually hurt readability.
+Style/GuardClause:
+  Enabled: false
+
+# Use postfix (modifier) conditionals for one-liners, unless doing so would
+# exceed 60 characters.
+Style/IfUnlessModifier:
+  Enabled: false
+
+# The Ruby Style Guide says:
+#
+# > Use \ instead of + or << to concatenate two string literals at line end.
+#
+# but in my experience the `\` style is rarely used and less readable. Please
+# concatenate multiline strings with `+` or use a HEREDOC.
+Style/LineEndConcatenation:
+  Enabled: false
+
+# Using `module_function` instead of `extend self` would make the instance
+# methods in these modules private. That would be a breaking change, so these
+# modules are excluded. See discussion in:
+# - https://github.com/airblade/paper_trail/pull/756
+# - https://github.com/bbatsov/ruby-style-guide/issues/556
+Style/ModuleFunction:
+  Exclude:
+    - 'lib/paper_trail/serializers/json.rb'
+    - 'lib/paper_trail/serializers/yaml.rb'
+
+# The Ruby Style Guide does not prescribe a particular quote character, only
+# that a project should pick one and be consistent. The decision has no
+# performance implications. Double quotes are slightly easier to read.
+Style/StringLiterals:
+  Enabled: false
+  EnforcedStyle: single_quotes

.rubocop_todo.yml

@@ -0,0 +1,33 @@
+require: rubocop-rspec
+
+# Remove these configuration records
+# one by one as the offenses are removed from the code base.
+
+Metrics/AbcSize:
+  Max: 22 # Goal: 15
+
+Metrics/CyclomaticComplexity:
+  Max: 8 # Goal: 6
+
+Metrics/PerceivedComplexity:
+  Max: 9 # Goal: 7
+
+RSpec/InstanceVariable:
+  Exclude:
+    - spec/paper_trail/associations/belongs_to_spec.rb
+    - spec/paper_trail/associations/habtm_spec.rb
+    - spec/paper_trail/associations/has_many_through_spec.rb
+    - spec/paper_trail/model_spec.rb
+
+RSpec/NestedGroups:
+  Exclude:
+    - spec/paper_trail/associations/belongs_to_spec.rb
+    - spec/paper_trail/associations/habtm_spec.rb
+    - spec/paper_trail/associations/has_many_through_spec.rb
+    - spec/paper_trail/model_spec.rb
+
+# It may be possible for us to use safe_load, but we'd have to pass the
+# safelists, like `whitelist_classes` into our serializer, and the serializer
+# interface is a public API, so that would be a breaking change.
+Security/YAMLLoad:
+  Enabled: false