sorcery 0.9.1 → 0.16.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5c0e37f33ed4fa3e085ccc8e3a6a5526afb632f2
-  data.tar.gz: 1b224ad20e8ed01e04a2b7a25153e5949b56fa4f
+SHA256:
+  metadata.gz: f2d091c4af06b65d0b8640aa1664cc03370f0859a0d37ccca2865813a41956ec
+  data.tar.gz: c60ee8af595868a99ddced5363716f6593f494bb82e97a82d35769b4a1c223e4
 SHA512:
-  metadata.gz: 48d1dd07a9ab99ade78c490bfffd27144b3951d5ba1f45bcfc1baede6db4cbe228e8916025bfd69fbc48d3342724b00ac2cfd9ecc41110d1b9fdd9559885091b
-  data.tar.gz: 250ceb737b38dab40dd3e16488f3e37aadf2b09fe94c6147ed92a2d42aab2d61d01601b3a2891403f70cc23ef4e675f4fb1ad83072d59ee71d8d6e5fd9d9c20d
+  metadata.gz: 24281e4ee0082665b792c467fbc9f7e70a6d3f26492a66de179248b6d3c97dcabf2aa3058e44239961ffa01645708883d22e097ac28dfc2b64e38ef2743a03c3
+  data.tar.gz: 55c173b3a0ea39d8067bb26b737e57548fb67357c0969d1eb08290c8876294157f2ca7c17888874d208d88fe893840b4046bf3463c1ead9fa16c15358a9d5668

data/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: athix

data/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,24 @@
+<!-- Please complete all sections. -->
+
+### Configuration
+
+- Sorcery Version: ``
+- Ruby Version: ``
+- Framework: ``
+- Platform: ``
+
+### Expected Behavior
+
+<!-- Tell us what should happen. -->
+
+### Actual Behavior
+
+<!-- Tell us what happens instead. -->
+
+### Steps to Reproduce
+
+<!-- Please list all steps to reproduce the issue. -->
+
+1.
+2.
+3.

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+Please ensure your pull request includes the following:
+
+- [ ] Description of changes
+- [ ] Update to CHANGELOG.md with short description and link to pull request
+- [ ] Changes have related RSpec tests that ensure functionality does not break
+
+<!-- For the changelog, please add your entry to the HEAD section. Do not create a new release header. -->

data/.github/workflows/ruby.yml

@@ -0,0 +1,70 @@
+name: Test Suite
+
+# Run against all commits and pull requests.
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  push:
+  pull_request:
+
+jobs:
+  test_matrix:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.4
+          - 2.5
+          - 2.6
+          - 2.7
+          - 3.0.0
+          # - 3.1
+
+        rails:
+          - '52'
+          - '60'
+          - '61'
+          # - '70'
+
+        exclude:
+          - ruby: 2.4
+            rails: '60'
+          - ruby: 2.4
+            rails: '61'
+          # - ruby: 2.4
+          #   rails: '70'
+          # - ruby: 2.5
+          #   rails: '70'
+          # - ruby: 2.6
+          #   rails: '70'
+          - ruby: 3.0.0
+            rails: '52'
+          # - ruby: 3.1
+          #   rails: '52'
+          # - ruby: 3.1
+          #   rails: '60'
+          # - ruby: 3.1
+          #   rails: '61'
+
+    env:
+      BUNDLE_GEMFILE: gemfiles/rails_${{ matrix.rails }}.gemfile
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake spec
+
+  finish:
+    runs-on: ubuntu-latest
+    needs: [ test_matrix ]
+    steps:
+      - name: Wait for status checks
+        run: echo "All Green!"

data/.gitignore

@@ -14,6 +14,9 @@ doc
 # jeweler generated
 pkg
 
+# byebug generated
+.byebug_history
+
 # for RVM
 .rvmrc
 

data/.rubocop.yml

@@ -0,0 +1,55 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  Exclude:
+    - 'lib/generators/sorcery/templates/**/*'
+  TargetRubyVersion: 2.6
+
+# See: https://github.com/rubocop-hq/rubocop/issues/3344
+Style/DoubleNegation:
+  Enabled: false
+
+####################
+## Pre-1.0.0 Code ##
+####################
+
+Metrics/AbcSize:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Metrics/BlockLength:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Layout/LineLength:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Metrics/MethodLength:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Naming/AccessorMethodName:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Naming/PredicateName:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'
+Style/Documentation:
+  Exclude:
+    - 'lib/**/*'
+    - 'spec/**/*'

data/.rubocop_todo.yml

@@ -0,0 +1,163 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2021-04-04 05:00:11 UTC using RuboCop version 0.88.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# Configuration parameters: Include.
+# Include: **/*.gemspec
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'sorcery.gemspec'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_braces
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+# Offense count: 83
+# Cop supports --auto-correct.
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Enabled: false
+
+# Offense count: 3
+# Cop supports --auto-correct.
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/sorcery/controller/submodules/external.rb'
+
+# Offense count: 2
+# Configuration parameters: AllowSafeAssignment.
+Lint/AssignmentInCondition:
+  Exclude:
+    - 'spec/rails_app/app/controllers/sorcery_controller.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Lint/NonDeterministicRequireOrder:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+# Offense count: 4
+# Cop supports --auto-correct.
+Lint/RedundantCopDisableDirective:
+  Exclude:
+    - 'lib/sorcery/controller.rb'
+    - 'lib/sorcery/model.rb'
+    - 'spec/rails_app/config/application.rb'
+    - 'spec/shared_examples/user_shared_examples.rb'
+
+# Offense count: 4
+# Cop supports --auto-correct.
+Lint/SendWithMixinArgument:
+  Exclude:
+    - 'lib/sorcery.rb'
+    - 'lib/sorcery/engine.rb'
+    - 'lib/sorcery/test_helpers/internal/rails.rb'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: IgnoreEmptyBlocks, AllowUnusedKeywordArguments.
+Lint/UnusedBlockArgument:
+  Exclude:
+    - 'spec/shared_examples/user_shared_examples.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SingleLineConditionsOnly, IncludeTernaryExpressions.
+# SupportedStyles: assign_to_condition, assign_inside_condition
+Style/ConditionalAssignment:
+  Exclude:
+    - 'lib/sorcery/adapters/active_record_adapter.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/ExpandPathArguments:
+  Exclude:
+    - 'spec/rails_app/config.ru'
+
+# Offense count: 1
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: annotated, template, unannotated
+Style/FormatStringToken:
+  Exclude:
+    - 'lib/generators/sorcery/install_generator.rb'
+
+# Offense count: 125
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: always, always_true, never
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Offense count: 3
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, UseHashRocketsWithSymbolValues, PreferHashRocketsForNonAlnumEndingSymbols.
+# SupportedStyles: ruby19, hash_rockets, no_mixed_keys, ruby19_no_mixed_keys
+Style/HashSyntax:
+  Exclude:
+    - 'lib/sorcery/adapters/active_record_adapter.rb'
+    - 'lib/sorcery/test_helpers/rails/integration.rb'
+
+# Offense count: 34
+# Cop supports --auto-correct.
+Style/IfUnlessModifier:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/sorcery/providers/line.rb'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+Style/RedundantBegin:
+  Exclude:
+    - 'lib/sorcery/controller.rb'
+    - 'lib/sorcery/model.rb'
+
+# Offense count: 4
+# Cop supports --auto-correct.
+# Configuration parameters: ConvertCodeThatCanStartToReturnNil, AllowedMethods.
+# AllowedMethods: present?, blank?, presence, try, try!
+Style/SafeNavigation:
+  Exclude:
+    - 'lib/sorcery/controller/config.rb'
+    - 'lib/sorcery/controller/submodules/brute_force_protection.rb'
+    - 'lib/sorcery/controller/submodules/remember_me.rb'
+    - 'lib/sorcery/model.rb'
+
+# Offense count: 7
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'spec/controllers/controller_oauth2_spec.rb'
+    - 'spec/sorcery_crypto_providers_spec.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, MinSize.
+# SupportedStyles: percent, brackets
+Style/SymbolArray:
+  Exclude:
+    - 'Rakefile'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+Style/UnpackFirst:
+  Exclude:
+    - 'lib/sorcery/crypto_providers/aes256.rb'
+    - 'spec/sorcery_crypto_providers_spec.rb'

data/CHANGELOG.md

@@ -1,8 +1,135 @@
 # Changelog
-
-## 1.0 (not released yet)
+## HEAD
+
+## 0.16.3
+
+* Fix provider instantiation for plural provider names (eg. okta) [#305](https://github.com/Sorcery/sorcery/pull/305)
+
+## 0.16.2
+
+* Inline core migration index definition [#281](https://github.com/Sorcery/sorcery/pull/281)
+* Add missing remember_me attributes to config [#180](https://github.com/Sorcery/sorcery/pull/180)
+* Fix MongoID adapter breaking on save [#284](https://github.com/Sorcery/sorcery/pull/284)
+* Don't pass token to Slack in query params. Prevents 'invalid_auth' error [#287](https://github.com/Sorcery/sorcery/pull/287)
+* Fix valid_password? not using configured values when called alone [#293](https://github.com/Sorcery/sorcery/pull/293)
+
+## 0.16.1
+
+* Fix default table name being incorrect in migration generator [#274](https://github.com/Sorcery/sorcery/pull/274)
+* Update `oauth` dependency per CVE-2016-11086
+
+## 0.16.0
+
+* Add BattleNet Provider [#260](https://github.com/Sorcery/sorcery/pull/260)
+* Fix failing isolated tests [#249](https://github.com/Sorcery/sorcery/pull/249)
+* Support LINE login v2.1 [#251](https://github.com/Sorcery/sorcery/pull/251)
+* Update generators to better support namespaces [#237](https://github.com/Sorcery/sorcery/pull/237)
+* Add support for Rails 6 [#238](https://github.com/Sorcery/sorcery/pull/238)
+* Fix ruby 2.7 deprecation warnings [#241](https://github.com/Sorcery/sorcery/pull/241)
+* Use set to ensure unique arrays [#233](https://github.com/Sorcery/sorcery/pull/233)
+
+## 0.15.1
+
+* Update `oauth` dependency per CVE-2016-11086
+
+## 0.15.0
+
+* Fix brute force vuln due to callbacks no being ran [#235](https://github.com/Sorcery/sorcery/pull/235)
+* Revert on_load change due to breaking existing applications [#234](https://github.com/Sorcery/sorcery/pull/234)
+* Add forget_me! and force_forget_me! test cases [#216](https://github.com/Sorcery/sorcery/pull/216)
+* In `generic_send_email`, check responds_to [#211](https://github.com/Sorcery/sorcery/pull/211)
+* Fix typo [#219](https://github.com/Sorcery/sorcery/pull/219)
+* Fix deprecation warnings in Rails 6 [#209](https://github.com/Sorcery/sorcery/pull/209)
+* Add ruby 2.6.5 to the travis build [#215](https://github.com/Sorcery/sorcery/pull/215)
+* Add discord provider [#185](https://github.com/Sorcery/sorcery/pull/185)
+* Remove MySQL database creation call [#214](https://github.com/Sorcery/sorcery/pull/214)
+* Use id instead of uid for VK provider [#199](https://github.com/Sorcery/sorcery/pull/199)
+* Don't :return_t JSON requests after login [#197](https://github.com/Sorcery/sorcery/pull/197)
+* Fix email scope for LinkedIn Provider [#191](https://github.com/Sorcery/sorcery/pull/191)
+* Ignore cookies when undefined cookies [#187](https://github.com/Sorcery/sorcery/pull/187)
+* Allow for custom providers with multi-word class names. [#190](https://github.com/Sorcery/sorcery/pull/190)
+
+## 0.14.0
+
+* Update LinkedIn to use OAuth 2 [#189](https://github.com/Sorcery/sorcery/pull/189)
+* Support the LINE login auth [#80](https://github.com/Sorcery/sorcery/pull/80)
+* Allow BCrypt to have app-specific secret token [#173](https://github.com/Sorcery/sorcery/pull/173)
+* Add #change_password method to reset_password module. [#165](https://github.com/Sorcery/sorcery/pull/165)
+* Clean up initializer comments [#153](https://github.com/Sorcery/sorcery/pull/153)
+* Allow load_from_magic_login_token to accept a block [#152](https://github.com/Sorcery/sorcery/pull/152)
+* Fix CipherError class name [#142](https://github.com/Sorcery/sorcery/pull/142)
+* Fix `update_failed_logins_count` being called twice when login failed [#163](https://github.com/Sorcery/sorcery/pull/163)
+* Update migration templates to use new hash syntax [#170](https://github.com/Sorcery/sorcery/pull/170)
+* Support for Rails 4.2 and lower soft-dropped [#171](https://github.com/Sorcery/sorcery/pull/171)
+
+## 0.13.0
+
+* Add support for Rails 5.2 / Ruby 2.5 [#129](https://github.com/Sorcery/sorcery/pull/129)
+* Fix migration files not being generated [#128](https://github.com/Sorcery/sorcery/pull/128)
+* Add support for ActionController::API [#133](https://github.com/Sorcery/sorcery/pull/133), [#150](https://github.com/Sorcery/sorcery/pull/150), [#159](https://github.com/Sorcery/sorcery/pull/159)
+* Update activation email to use after_commit callback [#130](https://github.com/Sorcery/sorcery/pull/130)
+* Add opt-in `invalidate_active_sessions!` method [#110](https://github.com/Sorcery/sorcery/pull/110)
+* Pass along `remember_me` to `#auto_login` [#136](https://github.com/Sorcery/sorcery/pull/136)
+* Respect SessionTimeout on login via RememberMe [#102](https://github.com/Sorcery/sorcery/pull/102)
+* Added `demodulize` on authentication class name association name fetch [#147](https://github.com/Sorcery/sorcery/pull/147)
+* Remove Gemnasium badge [#140](https://github.com/Sorcery/sorcery/pull/140)
+* Add Instragram provider [#51](https://github.com/Sorcery/sorcery/pull/51)
+* Remove `publish_actions` permission for facebook [#139](https://github.com/Sorcery/sorcery/pull/139)
+* Prepare for 1.0.0 [#157](https://github.com/Sorcery/sorcery/pull/157)
+* Add Auth0 provider [#160](https://github.com/Sorcery/sorcery/pull/160)
+
+## 0.12.0
+
+* Fix magic_login not inheriting from migration_class_name [#99](https://github.com/Sorcery/sorcery/pull/99)
+* Update YARD dependency [#100](https://github.com/Sorcery/sorcery/pull/100)
+* Make `#update_attributes` behave like `#update` [#98](https://github.com/Sorcery/sorcery/pull/98)
+* Add tests to the magic login submodule [#95](https://github.com/Sorcery/sorcery/pull/95)
+* Set user.stretches to 1 in test env by default [#81](https://github.com/Sorcery/sorcery/pull/81)
+* Allow user to be loaded from other source when session expires. fix #89 [#94](https://github.com/Sorcery/sorcery/pull/94)
+* Added a new ArgumentError for not defined user_class in config [#82](https://github.com/Sorcery/sorcery/pull/82)
+* Updated Required Ruby version to 2.2 [#85](https://github.com/Sorcery/sorcery/pull/85)
+* Add configuration for token randomness [#67](https://github.com/Sorcery/sorcery/pull/67)
+* Add facebook user_info_path option to initializer.rb [#63](https://github.com/Sorcery/sorcery/pull/63)
+* Add new function: `build_from` (allows building a user instance from OAuth without saving) [#54](https://github.com/Sorcery/sorcery/pull/54)
+* Add rubocop configuration and TODO list [#107](https://github.com/Sorcery/sorcery/pull/107)
+* Add support for VK OAuth (thanks to @Hirurg103) [#109](https://github.com/Sorcery/sorcery/pull/109)
+* Fix token leak via referrer header [#56](https://github.com/Sorcery/sorcery/pull/56)
+* Add `login_user` helper for request specs [#57](https://github.com/Sorcery/sorcery/pull/57)
+
+## 0.11.0
+
+* Refer to User before calling remove_const to avoid NameError [#58](https://github.com/Sorcery/sorcery/pull/58)
+* Resurrect block authentication, showing auth failure reason. [#41](https://github.com/Sorcery/sorcery/pull/41)
+* Add github scope option to initializer.rb [#50](https://github.com/Sorcery/sorcery/pull/50)
+* Fix Facebook being broken due to API deprecation [#53](https://github.com/Sorcery/sorcery/pull/53)
+
+## 0.10.3
+
+* Revert removal of MongoID Adapter (breaks Sorcery for MongoID users until separate gem is created) [#45](https://github.com/Sorcery/sorcery/pull/45)
+
+## 0.10.2
+
+* Added support for Microsoft OAuth (thanks to @athix) [#37](https://github.com/Sorcery/sorcery/pull/37)
+
+## 0.10.1
+
+* Fixed LinkedIn bug [#36](https://github.com/Sorcery/sorcery/pull/36)
+
+## 0.10.0
 
 * Adapters (Mongoid, MongoMapper, DataMapper) are now separated from the core Sorcery repo and moved under `sorcery-rails` organization. Special thanks to @juike!
+* `current_users` method was removed
+* Added `logged_in?` `logged_out?` `online?` to activity_logging instance methods
+* Added support for PayPal OAuth (thanks to @rubenmoya)
+* Added support for Slack OAuth (thanks to @youzik)
+* Added support for WeChat OAuth (thanks to @Darmody)
+* Deprecated Rails 3
+  * Deprecated using `callback_filter` in favor of `callback_action`
+  * Added null: false to migrations
+* Added support for Rails 5 (thanks to @kyuden)
+* Added support for Ruby 2.4 (thanks to @kyuden)
+* Added WeChat provider to external submodule.
+* Namespace login lock/unlock methods to fix conflicts with Rails lock/unlock (thanks to @kyuden)
 
 ## 0.9.1
 
@@ -63,7 +190,7 @@
 
 ## 0.8.4
 
-  * Few security fixes in `external` module
+* Few security fixes in `external` module
 
 ## 0.8.3 (yanked because of bad Jeweler release)
 
@@ -71,38 +198,9 @@
 
 * Activity logging feature has a new column called `last_login_from_ip_address` (string type). If you use ActiveRecord, you will have to add this column to DB ([#465](https://github.com/NoamB/sorcery/issues/465))
 
-## 0.8.1
-<!-- TO BE WRITTEN -->
-
-## 0.8.0
-<!-- TO BE WRITTEN -->
-
-## 0.7.13
-<!-- TO BE WRITTEN -->
-
-## 0.7.12
-<!-- TO BE WRITTEN -->
-
-## 0.7.11
-<!-- TO BE WRITTEN -->
-
-## 0.7.10
-<!-- TO BE WRITTEN -->
-
-## 0.7.9
-<!-- TO BE WRITTEN -->
-
-## 0.7.8
-<!-- TO BE WRITTEN -->
-
-## 0.7.7
-<!-- TO BE WRITTEN -->
-
-## 0.7.6
-<!-- TO BE WRITTEN -->
+## 0.7.5-0.8.1
 
-## 0.7.5
-<!-- TO BE WRITTEN -->
+<!-- HERE BE DRAGONS (Changelogs never written) -->
 
 ## 0.7.1-0.7.4
 

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# The Sorcery Community Code of Conduct
+
+This document provides a few simple community guidelines for a safe, respectful,
+productive, and collaborative place for any person who is willing to contribute
+to the Sorcery community. It applies to all "collaborative spaces", which are
+defined as community communications channels (such as mailing lists, submitted
+patches, commit comments, etc.).
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal
+  attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always
+  assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.

data/Gemfile

@@ -1,22 +1,8 @@
 source 'https://rubygems.org'
 
-gem 'rails', '~> 3.2'
-gem 'sqlite3'
 gem 'pry'
-
-group :mongomapper do
-  gem 'mongo_mapper'
-end
-
-group :mongoid do
-  gem 'mongoid', "~> 2.4.4"
-  gem 'bson_ext'
-end
-
-group :datamapper do
-  gem 'mysql2'
-  gem 'data_mapper'
-  gem 'dm-mysql-adapter'
-end
+gem 'rails'
+gem 'rails-controller-testing'
+gem 'sqlite3'
 
 gemspec

data/{LICENSE.txt → LICENSE.md}

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Noam Ben-Ari <mailto:nbenari@gmail.com>
+Copyright (c) 2010 [Noam Ben-Ari](mailto:nbenari@gmail.com)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/MAINTAINING.md

@@ -0,0 +1,64 @@
+# Maintaining Sorcery
+
+This will eventually be fleshed out so that anyone should be able to pick up and
+maintain Sorcery by following this guide. It will provide step-by-step guides
+for common tasks such as releasing new versions, as well as explain how to
+triage issues and keep the CHANGELOG up-to-date.
+
+## Table of Contents
+
+1. [Merging Pull Requests](#merging-pull-requests)
+1. [Versioning](#versioning)
+   1. [Version Naming](#version-naming)
+   1. [Releasing a New Version](#releasing-a-new-version)
+
+## Merging Pull Requests
+
+TODO
+
+## Versioning
+
+### Version Naming
+
+Sorcery uses semantic versioning which can be found at: https://semver.org/
+
+All versions of Sorcery should follow this format: `MAJOR.MINOR.PATCH`
+
+Where:
+
+* MAJOR - Includes backwards **incompatible** changes.
+* MINOR - Introduces new functionality but is fully backwards compatible.
+* PATCH - Fixes errors in existing functionality (must be backwards compatible).
+
+The changelog and git tags should use `vMAJOR.MINOR.PATCH` to indicate that the
+number represents a version of Sorcery. For example, `1.0.0` would become
+`v1.0.0`.
+
+### Releasing a New Version
+
+When it's time to release a new version, you'll want to ensure all the changes
+you need are on the master branch and that there is a passing build. Then follow
+this checklist and prepare a release commit:
+
+NOTE: `X.Y.Z` and `vX.Y.Z` are given as examples, and should be replaced with
+      whatever version you are releasing. See: [Version Naming](#version-naming)
+
+1. Update CHANGELOG.md
+   1. Check for any changes that have been included since the last release that
+      are not reflected in the changelog. Add any missing entries to the `HEAD`
+      section.
+   1. Check the changes in `HEAD` to determine what version increment is
+      appropriate. See [Version Naming](#version-naming) if unsure.
+   1. Replace `## HEAD` with `## vX.Y.Z` and create a new `## HEAD` section
+      above the latest version.
+1. Update Gem Version
+   1. Update `./lib/sorcery/version.rb` to 'X.Y.Z'
+1. Stage your changes and create a commit
+   1. `git add -A`
+   1. `git commit -m "Release vX.Y.Z"`
+1. TODO: Gem Release (WIP)
+   1. `cd <dir>`
+   1. `gem build`
+   1. `gem push <filename>`
+1. TODO: Version tagging
+   1. Release new version via github interface