Merge pull request #12 from fastruby/feature/readme

Update README.md

Author: etagwerker

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to OmbuLabs::Auth
+Have a fix for a problem you've been running into or an idea for a new feature you think would be useful? Bug reports and pull requests are welcome on GitHub at [https://github.com/fastruby/ombu_labs-auth](https://github.com/fastruby/ombu_labs-auth).
+
+Here's what you need to do:
+
+- Read and understand the [Code of Conduct](https://github.com/fastruby/ombu_labs-auth/blob/main/CODE_OF_CONDUCT.md).
+- Fork this repo and clone your fork to somewhere on your machine.
+- [Ensure that you have a working environment](#setting-up-your-environment)
+- Cut a new branch and write a failing test for the feature or bug fix you plan on implementing.
+- [Update the changelog when applicable](#a-word-on-the-changelog).
+- Read the guidelines when [Releasing a new version](#releasing-a-new-version)
+- Push to your fork and submit a pull request.
+- [Make sure the test suite passes on GitHub Actions and make any necessary changes to your branch to bring it to green.](#continuous-integration).
+
+## Setting up your environment
+To install the dependencies, run:
+
+```bash
+bin/setup
+```
+
+## A word on the changelog
+You may also notice that we have a changelog in the form of [CHANGELOG.md](CHANGELOG.md). We use a format based on [Keep A Changelog](https://keepachangelog.com/en/1.0.0/).
+
+The important things to keep in mind are:
+
+- If your PR closes any open GitHub issue, make sure you include `Closes #XXXX` in your comment.
+- New additions get added under the main (unreleased) heading;
+- Attach a link to the PR with the following format:
+
+* [<FEATURE | BUGFIX >: Description of changes](github.com/link/to/pr).
+
+## Releasing a new version
+To release a new version, update the version number in `version.rb`.
+
+To create a git tag for the version, push git commits and tags, and push the `.gem` file to rubygems.org, run:
+
+`bundle exec rake release`
+
+## When Submitting a Pull Request:
+* If your PR closes any open GitHub issues, please include `Closes #XXXX` in your comment.
+* Please include a summary of the change and which issue is fixed or which feature is introduced.
+* If changes to the behavior are made, clearly describe what are the changes and why.
+* If changes to the UI are made, please include screenshots of the before and after.
+
+## Continuous integration
+After opening your Pull Request, please make sure that all tests pass on the CI, to make sure your changes work in all possible environments. GitHub Actions will kick in after you push up a branch or open a PR.
+
+If the build fails, click on a failed job and scroll through its output to verify what is the problem. Push your changes to your branch until the build is green.

README.md

@@ -1,28 +1,82 @@
 # OmbuLabs::Auth
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+This gem provides an easy way to generate new (Devise) sessions for members of a GitHub organization.
 
-## Installation
-Add this line to your application's Gemfile:
+If a user is signing in with GitHub and they are a (public) member of the configured GitHub organization, they will be allowed in.
+
+## Environment Variables
+Make sure you configure your ENV variables to use Github authentication.
+
+```
+ENV["GITHUB_APP_ID"]
+ENV["GITHUB_APP_SECRET"]
+ENV["ORGANIZATION_LOGIN"]
+```
+
+`ORGANIZATION_LOGIN`: This is the organization name as it appears in the GitHub URL, for instance `orgname` in https://github.com/orgname. It is needed to check if users are a part of the organization. Ensure that your membership is set to _public_ when you visit https://github.com/orgs/orgname/people.
+
+If you don't belong to any organization, you can set up one here: https://github.com/organizations/plan
+
+Make sure you add your organization to the `.env` file like this:
+
+```
+ORGANIZATION_LOGIN=orgname
+```
+
+`GITHUB_APP_ID` and `GITHUB_APP_SECRET`: These are the credentials of the OAuth GitHub App that you need to create. Follow the instructions on this link to create one: [Creating an OAuth GitHub App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)
+
+When creating the OAuth GitHub App, the `Homepage URL` field should be set to http://localhost:3000, and the `Authorization callback URL` should be http://localhost:3000/users/auth/github/callback.
+
+Once you create the app and generate credentials for it, make sure you add them to the `.env` file like this:
+
+```
+GITHUB_APP_ID=xxxxxxxxxxxxxxxxxxxx
+GITHUB_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+## Getting Started
+
+- Add these lines to your application's Gemfile:
 
 ```ruby
-gem "ombu_labs-auth"
+gem 'ombu_labs-auth'
+gem 'omniauth-github', '~> 2.0.0'
 ```
 
-And then execute:
+- And then execute:
 ```bash
 $ bundle
 ```
 
-Or install it yourself as:
-```bash
-$ gem install ombu_labs-auth
+- Add the following line to `config/routes.rb`
+
+```ruby
+mount OmbuLabs::Auth::Engine, at: '/', as: 'ombu_labs_auth'
 ```
 
+- Add a Devise signin link in your homepage (notice all URL helpers will be under the engine object `ombu_labs_auth`)
+
+```html
+<div>
+  <h1>Welcome to the App</h1>
+  <%= link_to "Sign in", ombu_labs_auth.new_user_session_path %>
+</div>
+```
+
+- Add the Devise authentication helper to your private objects controllers
+
+```
+before_action :authenticate_user!
+```
+
+## Caveats
+
+Please be aware this gem is a mountable engine which depends on Devise, and it's not possible to mount it multiple times. Refer to their Wiki for more on the issue - https://github.com/heartcombo/devise/wiki/How-To:-Use-devise-inside-a-mountable-engine
+
 ## Contributing
-Contribution directions go here.
+
+Have a fix for a problem you've been running into or an idea for a new feature you think would be useful?
+
+Take a look at the [Contributing document](https://github.com/fastruby/ombu_labs-auth/blob/main/CONTRIBUTING.md) for instructions to set up the repo on your machine and create a good Pull Request.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here