📝 Improve documentation

omniauth · Nov 15, 2024 · 028273e · 028273e
1 parent ab59f71
commit 028273e
Show file tree

Hide file tree

Showing 2 changed files with 230 additions and 36 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
-Copyright (c) 2021 OmniAuth-Identity Maintainers
-Copyright (c) 2020 Peter Boling, Andrew Roberts, and Jellybooks Ltd.
-Copyright (c) 2010-2015 Michael Bleigh and Intridea, Inc.
+Copyright (c) 2021, 2024 Peter H. Boling, and OmniAuth-Identity Maintainers
+Copyright (c) 2020 Peter H. Boling, Andrew Roberts, and Jellybooks Ltd.
+Copyright (c) 2010-2015 Michael Bleigh, and Intridea, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

diff --git a/README.md b/README.md
@@ -1,42 +1,115 @@
-# OmniAuth Identity
-
-[![Version](https://img.shields.io/gem/v/omniauth-identity.svg)](https://rubygems.org/gems/omniauth-identity)
-[![Depfu](https://badges.depfu.com/badges/6c9b45362951b872127f9e46d39bed76/count.svg)](https://depfu.com/github/omniauth/omniauth-identity?project_id=22381)
-[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fomniauth%2Fomniauth-identity%2Fbadge&style=flat)](https://actions-badge.atrox.dev/omniauth/omniauth-identity/goto)
-[![Maintainability](https://api.codeclimate.com/v1/badges/621d6211cb2e0959ce00/maintainability)](https://codeclimate.com/github/omniauth/omniauth-identity/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/621d6211cb2e0959ce00/test_coverage)](https://codeclimate.com/github/omniauth/omniauth-identity/test_coverage)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![Open Source Helpers](https://www.codetriage.com/omniauth/omniauth-identity/badges/users.svg)](https://www.codetriage.com/omniauth/omniauth-identity)
-[![Downloads Rank](https://img.shields.io/gem/rd/omniauth-identity.svg)](https://rubygems.org/gems/omniauth-identity)
+# `OmniAuth::Identity`
+
+[![Version][👽versioni]][👽version]
+[![License: MIT][📄license-img]][📄license-ref]
+[![Downloads Rank][👽dl-ranki]][👽dl-rank]
+[![Open Source Helpers][👽oss-helpi]][👽oss-help]
+[![Depfu][🔑depfui♻️]][🔑depfu]
+[![CodeCov][🔑codecovi♻️]][🔑codecov]
+[![Test Coverage][🔑cc-covi♻️]][🔑cc-cov]
+[![Maintainability][🔑cc-mnti♻️]][🔑cc-mnt]
+[![CI Supported Build][🚎6-s-wfi]][🚎6-s-wf]
+[![CI Legacy Build][🚎4-lg-wfi]][🚎4-lg-wf]
+[![CI Unsupported Build][🚎7-us-wfi]][🚎7-us-wf]
+[![CI Heads Build][🚎3-hd-wfi]][🚎3-hd-wf]
+[![CI Ancient Build][🚎1-an-wfi]][🚎1-an-wf]
+[![CI Coverage Build][🚎2-cov-wfi]][🚎2-cov-wf]
+[![CI Style Build][🚎5-st-wfi]][🚎5-st-wf]
+
+[comment]: <> ( 👽️ INFO LINKS )
+
+[👽dl-rank]: https://rubygems.org/gems/omniauth-identity
+[👽dl-ranki]: https://img.shields.io/gem/rd/omniauth-identity.svg
+[👽oss-help]: https://www.codetriage.com/omniauth/omniauth-identity
+[👽oss-helpi]: https://www.codetriage.com/omniauth/omniauth-identity/badges/users.svg
+[👽version]: https://rubygems.org/gems/omniauth-identity
+[👽versioni]: https://img.shields.io/gem/v/omniauth-identity.svg
+
+[comment]: <> ( 🔑 KEYED LINKS )
+
+[🔑cc-mnt]: https://codeclimate.com/github/omniauth/omniauth-identity/maintainability
+[🔑cc-mnti♻️]: https://api.codeclimate.com/v1/badges/621d6211cb2e0959ce00/maintainability
+[🔑cc-cov]: https://codeclimate.com/github/omniauth/omniauth-identity/test_coverage
+[🔑cc-covi♻️]: https://api.codeclimate.com/v1/badges/621d6211cb2e0959ce00/test_coverage
+[🔑codecov]: https://codecov.io/gh/omniauth/omniauth-identity
+[🔑codecovi♻️]: https://codecov.io/gh/omniauth/omniauth-identity/graph/badge.svg?token=selEoMrZzA
+[🔑depfu]: https://depfu.com/github/omniauth/omniauth-identity
+[🔑depfui♻️]: https://badges.depfu.com/badges/6c9b45362951b872127f9e46d39bed76/count.svg
+
+[comment]: <> ( 🚎 BUILD LINKS )
+
+[🚎1-an-wf]: https://github.com/omniauth/omniauth-identity/actions/workflows/ancient.yml
+[🚎1-an-wfi]: https://github.com/omniauth/omniauth-identity/actions/workflows/ancient.yml/badge.svg
+[🚎2-cov-wf]: https://github.com/omniauth/omniauth-identity/actions/workflows/coverage.yml
+[🚎2-cov-wfi]: https://github.com/omniauth/omniauth-identity/actions/workflows/coverage.yml/badge.svg
+[🚎3-hd-wf]: https://github.com/omniauth/omniauth-identity/actions/workflows/heads.yml
+[🚎3-hd-wfi]: https://github.com/omniauth/omniauth-identity/actions/workflows/heads.yml/badge.svg
+[🚎4-lg-wf]: https://github.com/omniauth/omniauth-identity/actions/workflows/legacy.yml
+[🚎4-lg-wfi]: https://github.com/omniauth/omniauth-identity/actions/workflows/legacy.yml/badge.svg
+[🚎5-st-wf]: https://github.com/omniauth/omniauth-identity/actions/workflows/style.yml
+[🚎5-st-wfi]: https://github.com/omniauth/omniauth-identity/actions/workflows/style.yml/badge.svg
+[🚎6-s-wf]: https://github.com/omniauth/omniauth-identity/actions/workflows/supported.yml
+[🚎6-s-wfi]: https://github.com/omniauth/omniauth-identity/actions/workflows/supported.yml/badge.svg
+[🚎7-us-wf]: https://github.com/omniauth/omniauth-identity/actions/workflows/unsupported.yml
+[🚎7-us-wfi]: https://github.com/omniauth/omniauth-identity/actions/workflows/unsupported.yml/badge.svg
+
+-----
+
+[![Liberapay Patrons][⛳liberapay-img]][⛳liberapay]
+[![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor]
+[![Polar Shield][🖇polar-img]][🖇polar]
+[![Donate to my FLOSS or refugee efforts at ko-fi.com][🖇kofi-img]][🖇kofi]
+[![Donate to my FLOSS or refugee efforts using Patreon][🖇patreon-img]][🖇patreon]
+
+[⛳liberapay-img]: https://img.shields.io/liberapay/patrons/pboling.svg?logo=liberapay
+[⛳liberapay]: https://liberapay.com/pboling/donate
+[🖇sponsor-img]: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github
+[🖇sponsor]: https://github.com/sponsors/pboling
+[🖇polar-img]: https://polar.sh/embed/seeks-funding-shield.svg?org=pboling
+[🖇polar]: https://polar.sh/pboling
+[🖇kofi-img]: https://img.shields.io/badge/buy%20me%20coffee-donate-yellow.svg
+[🖇kofi]: https://ko-fi.com/O5O86SNP4
+[🖇patreon-img]: https://img.shields.io/badge/patreon-donate-yellow.svg
+[🖇patreon]: https://patreon.com/galtzo
 
 The OmniAuth Identity gem provides a way for applications to utilize a
 traditional username/password based authentication system without the need
 to give up the simple authentication flow provided by OmniAuth. Identity
 is designed on purpose to be as featureless as possible: it provides the
 basic construct for user management and then gets out of the way.
 
-## Compatibility
-
-This gem is compatible with, as of Nov 2024, version 3:
-
-* Latest released version of omniauth, v2+
-* Ruby 2.4, 2.5, 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, ruby-head, truffleruby-head, jruby-head
-* At least 5 different database ORM adapters, which connect to 15 different database clients!
-
-| Databases | Adapter Libraries |
-|--------- | -------- |
-| MySQL, PostgreSQL, SQLite3 | [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) |
-| CouchDB | [CouchPotato](https://github.com/langalex/couch_potato) |
-| MongoDB | [Mongoid](https://github.com/mongodb/mongoid) |
-| RethinkDB | [NoBrainer](http://nobrainer.io/) |
-| ADO, Amalgalite, IBM_DB, JDBC, MySQL, Mysql2, ODBC, Oracle, PostgreSQL, SQLAnywhere, SQLite3, and TinyTDS | [Sequel](http://sequel.jeremyevans.net) |
+| Primary Namespace | `OmniAuth::Identity`                                                                                                                                                                                                                                                                                                                                     |
+|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| documentation     | [on Github.com][homepage], [on RubyDoc.info][documentation]                                                                                                                                                                                                                                                                                              |
+| expert support    | [![Get help on Codementor](https://cdn.codementor.io/badges/get_help_github.svg)](https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github)                                                                                                                                                    |
+| `...` 💖          | [![Follow Me on LinkedIn][🖇linkedin-img]][🖇linkedin] [![Find Me on WellFound:][✌️wellfound-img]][✌️wellfound] [![Find Me on CrunchBase][💲crunchbase-img]][💲crunchbase] [![My LinkTree][🌳linktree-img]][🌳linktree] [![Follow Me on Ruby.Social][🐘ruby-mast-img]][🐘ruby-mast] [![Tweet @ Peter][🐦tweet-img]][🐦tweet] [💻][coderme] [🌏][aboutme] |
+
+<!-- 7️⃣ spread 💖 -->
+[🐦tweet-img]: https://img.shields.io/twitter/follow/galtzo.svg?style=social&label=Follow%20%40galtzo
+[🐦tweet]: http://twitter.com/galtzo
+[🚎blog]: http://www.railsbling.com/tags/omniauth-identity/
+[🚎blog-img]: https://img.shields.io/badge/blog-railsbling-brightgreen.svg?style=flat
+[🖇linkedin]: http://www.linkedin.com/in/peterboling
+[🖇linkedin-img]: https://img.shields.io/badge/PeterBoling-blue?style=plastic&logo=linkedin
+[✌️wellfound]: https://angel.co/u/peter-boling
+[✌️wellfound-img]: https://img.shields.io/badge/peter--boling-orange?style=plastic&logo=wellfound
+[💲crunchbase]: https://www.crunchbase.com/person/peter-boling
+[💲crunchbase-img]: https://img.shields.io/badge/peter--boling-purple?style=plastic&logo=crunchbase
+[🐘ruby-mast]: https://ruby.social/@galtzo
+[🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https%3A%2F%2Fruby.social&style=plastic&logo=mastodon&label=Ruby%20%40galtzo
+[🌳linktree]: https://linktr.ee/galtzo
+[🌳linktree-img]: https://img.shields.io/badge/galtzo-purple?style=plastic&logo=linktree
+
+<!-- Maintainer Contact Links -->
+[aboutme]: https://about.me/peter.boling
+[coderme]: https://coderwall.com/Peter%20Boling
 
 ## Installation
 
-To acquire the latest release from RubyGems add the following to your `Gemfile`:
+To acquire the latest release from RubyGems, and add this gem to your `Gemfile`, run:
 
 ```ruby
-gem "omniauth-identity"
+bundle add omniauth-identity 
 ```
 
 If the git repository has new commits not yet in an official release, simply specify the repo instead:
@@ -45,6 +118,23 @@ If the git repository has new commits not yet in an official release, simply spe
 gem "omniauth-identity", git: "https://github.com/omniauth/omniauth-identity.git"
 ```
 
+## Compatibility
+
+This gem is compatible with a wide range of Ruby versions and Ruby ORMs, as of Nov 2024, version 3.1.
+
+* Latest released version of omniauth, v2+
+* Tested in CI against Ruby 2.5, 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, ruby-head, truffleruby-head
+* Probably also compatible with Ruby 2.4 and jruby-head
+* At least 5 different database ORM adapters, which connect to 15 different database clients!
+
+| Databases                                                                                                 | Adapter Libraries                                                        |
+|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
+| MySQL, PostgreSQL, SQLite3                                                                                | [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) |
+| CouchDB                                                                                                   | [CouchPotato](https://github.com/langalex/couch_potato)                  |
+| MongoDB                                                                                                   | [Mongoid](https://github.com/mongodb/mongoid)                            |
+| RethinkDB                                                                                                 | [NoBrainer](http://nobrainer.io/)                                        |
+| ADO, Amalgalite, IBM_DB, JDBC, MySQL, Mysql2, ODBC, Oracle, PostgreSQL, SQLAnywhere, SQLite3, and TinyTDS | [Sequel](http://sequel.jeremyevans.net)                                  |
+
 ## Usage
 
 This can be a bit hard to understand the first time. Luckily, Ryan Bates made
@@ -109,7 +199,6 @@ class SequelTestIdentity < Sequel::Model(:identities)
 end
 ```
 
-
 ### Mongoid
 
 Include the `OmniAuth::Identity::Models::Mongoid` mixin and specify
@@ -354,12 +443,117 @@ bundle exec rake
 
 📌 Create new Pull Request with your changes 📌
 
-## License
+## 🤝 Contributing
+
+If you need some ideas of where to help, you could work on adding more code coverage,
+or if it is already 💯 (see [below](#code-coverage)) then check [issues][🤝issues], or [PRs][🤝pulls],
+or use the gem and think about how it could be better.
+
+Also, see [CONTRIBUTING.md][🤝contributing].
+
+[🤝issues]: https://github.com/omniauth/omniauth-identity/issues
+[🤝pulls]: https://github.com/omniauth/omniauth-identity/pulls
+[🤝contributing]: CONTRIBUTING.md
+
+### Code Coverage
+
+[![Coverage Graph][🔑codecov-g]][🖇codecov]
+
+[🔑codecov-g]: https://codecov.io/gh/omniauth/omniauth-identity/graphs/tree.svg?token=selEoMrZzA
+
+## 🌈 Contributors
+
+[![Contributors][🖐contributors-img]][🖐contributors]
+
+Made with [contributors-img][🖐contrib-rocks].
+
+[🖐contrib-rocks]: https://contrib.rocks
+[🖐contributors]: https://github.com/omniauth/omniauth-identity/graphs/contributors
+[🖐contributors-img]: https://contrib.rocks/image?repo=omniauth/omniauth-identity
 
-MIT License. See LICENSE for details.
+## Star History
 
-## Copyright
+<a href="https://star-history.com/#omniauth/omniauth-identity&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=omniauth/omniauth-identity&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=omniauth/omniauth-identity&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=omniauth/omniauth-identity&type=Date" />
+ </picture>
+</a>
 
-* Copyright (c) 2021 OmniAuth-Identity Maintainers
-* Copyright (c) 2020 Peter Boling, Andrew Roberts, and Jellybooks Ltd.
+## 🪇 Code of Conduct
+
+Everyone interacting in this project's codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the [code of conduct][🪇conduct].
+
+[🪇conduct]: CODE_OF_CONDUCT.md
+
+## 📌 Versioning
+
+This Library adheres to [Semantic Versioning 2.0.0][📌semver].
+Violations of this scheme should be reported as bugs.
+Specifically, if a minor or patch version is released that breaks backward compatibility,
+a new version should be immediately released that restores compatibility.
+Breaking changes to the public API will only be introduced with new major versions.
+
+To get a better understanding of how SemVer is intended to work over a project's lifetime,
+read this article from the creator of SemVer:
+
+- ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]
+
+As a result of this policy, you can (and should) specify a dependency on these libraries using
+the [Pessimistic Version Constraint][📌pvc] with two digits of precision.
+
+For example:
+
+```ruby
+spec.add_dependency("omniauth-identity", "~> 3.1")
+```
+
+See [CHANGELOG.md][📌changelog] for list of releases.
+
+[comment]: <> ( 📌 VERSIONING LINKS )
+
+[📌pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
+[📌semver]: http://semver.org/
+[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html
+[📌changelog]: CHANGELOG.md
+
+## 📄 License
+
+The gem is available as open source under the terms of
+the [MIT License][📄license] [![License: MIT][📄license-img]][📄license-ref].
+See [LICENSE.txt][📄license] for the official [Copyright Notice][📄copyright-notice-explainer].
+
+[comment]: <> ( 📄 LEGAL LINKS )
+
+[📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
+[📄license]: LICENSE.txt
+[📄license-ref]: https://opensource.org/licenses/MIT
+[📄license-img]: https://img.shields.io/badge/License-MIT-green.svg
+
+### © Copyright
+
+* Copyright (c) 2021, 2024 [Peter H. Boling][peterboling], and OmniAuth-Identity Maintainers
+* Copyright (c) 2020 [Peter H. Boling][peterboling], Andrew Roberts, and Jellybooks Ltd.
 * Copyright (c) 2010-2015 Michael Bleigh, and Intridea, Inc.
+
+[railsbling]: http://www.railsbling.com
+[peterboling]: http://www.peterboling.com
+[bundle-group-pattern]: https://gist.github.com/pboling/4564780
+[documentation]: http://rubydoc.info/gems/omniauth-identity
+[homepage]: https://github.com/omniauth/omniauth-identity
+
+## 🤑 One more thing
+
+You made it to the bottom of the page,
+so perhaps you'll indulge me for another 20 seconds.
+I maintain many dozens of gems, including this one,
+because I want Ruby to be a great place for people to solve problems, big and small.
+Please consider supporting my efforts via the giant yellow link below,
+or one of the others at the head of this README.
+
+[![Buy me a latte][🖇buyme-img]][🖇buyme]
+
+[🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff
+[🖇buyme]: https://www.buymeacoffee.com/pboling