docs: Updates README.md (#58)

.circleci/config.yml

@@ -95,6 +95,25 @@ jobs:
       - run: "cp ./docs/api.swagger.json ../docs/apis/oathkeeper.json"
       - run: "(cd ../docs && git add -A && git commit -a -m \"Updates ORY Oathkeeper Swagger definitions\" && git push origin) || exit 0"
 
+  changelog:
+    docker:
+      - image: circleci/ruby:2.4-node
+    steps:
+      - checkout
+      - run: gem install github_changelog_generator
+      - run: sudo npm i -g doctoc
+      - run: github_changelog_generator -u ory -p hydra -o CHANGELOG.md --token $GITHUB_TOKEN
+      - run: doctoc CHANGELOG.md
+      - run: doctoc README.md
+      - run: git config --global user.email "[email protected]"
+      - run: git config --global user.name "ORY Continuous Integration"
+      - run: git add CHANGELOG.md
+      - run: |
+          git commit -m "docs: Incorporates changes from version $(git describe --tags)" -- CHANGELOG.md
+      - run: git remote rm origin
+      - run: git remote add origin https://arekkas:[email protected]/ory/oathkeeper.git
+      - run: git push origin HEAD:master
+
 workflows:
   version: 2
   "test, build, and relase":
@@ -115,6 +134,10 @@ workflows:
           filters:
             branches:
               only: master
+      - changelog:
+          filters:
+            branches:
+              only: master
       - test-docker:
           requires:
             - test

CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contribution Guide
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Introduction](#introduction)
+- [Contributing Code](#contributing-code)
+- [Disclosing vulnerabilities](#disclosing-vulnerabilities)
+- [Code Style](#code-style)
+- [Developer’s Certificate of Origin](#developers-certificate-of-origin)
+- [Pull request procedure](#pull-request-procedure)
+- [Communication](#communication)
+- [Conduct](#conduct)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Introduction
+
+We welcome and encourage community contributions to ORY Oathkeeper.
+
+Since the project is still unstable, there are specific priorities for development. Pull requests that do not address these priorities will not be accepted until ORY Oathkeeper is production ready.
+
+Please familiarize yourself with the Contribution Guidelines and Project Roadmap before contributing.
+
+There are many ways to help ORY Oathkeeper besides contributing code:
+
+ - Fix bugs or file issues
+ - Improve the documentation
+
+## Contributing Code
+
+Unless you are fixing a known bug, we **strongly** recommend discussing it with the core team via a GitHub issue or [in our chat](https://www.ory.sh/chat) before getting started to ensure your work is consistent with ORY Oathkeeper's roadmap and architecture.
+
+All contributions are made via pull request. Note that **all patches from all contributors get reviewed**. After a pull request is made other contributors will offer feedback, and if the patch passes review a maintainer will accept it with a comment. When pull requests fail testing, authors are expected to update their pull requests to address the failures until the tests pass and the pull request merges successfully.
+
+At least one review from a maintainer is required for all patches (even patches from maintainers).
+
+Reviewers should leave a "LGTM" comment once they are satisfied with the patch. If the patch was submitted by a maintainer with write access, the pull request should be merged by the submitter after review.
+
+## Disclosing vulnerabilities
+
+Please disclose vulnerabilities exclusively to [[email protected]](mailto:[email protected]). Do not use GitHub issues.
+
+## Code Style
+
+Please follow these guidelines when formatting source code:
+
+* Go code should match the output of `gofmt -s`
+
+## Developer’s Certificate of Origin
+
+All contributions must include acceptance of the DCO:
+
+```text
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+660 York Street, Suite 102,
+San Francisco, CA 94110 USA
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+To accept the DCO, simply add this line to each commit message with your name and email address (`git commit -s` will do this for you):
+
+```text
+Signed-off-by: Jane Example <[email protected]>
+```
+
+For legal reasons, no anonymous or pseudonymous contributions are accepted ([contact us](mailto:[email protected]) if this is an issue).
+
+## Pull request procedure
+
+To make a pull request, you will need a GitHub account; if you are unclear on this process, see GitHub's documentation on [forking](https://help.github.com/articles/fork-a-repo) and [pull requests](https://help.github.com/articles/using-pull-requests). Pull requests should be targeted at the `master` branch. Before creating a pull request, go through this checklist:
+
+1. Create a feature branch off of `master` so that changes do not get mixed up.
+1. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your local changes against the `master` branch.
+1. Run the full project test suite with the `go test ./...` (or equivalent) command and confirm that it passes.
+1. Run `gofmt -s` (if the project is written in Go).
+1. Accept the Developer's Certificate of Origin on all commits (see above).
+1. Ensure that each commit has a subsystem prefix (ex: `controller: `).
+
+Pull requests will be treated as "review requests," and maintainers will give feedback on the style and substance of the patch.
+
+Normally, all pull requests must include tests that test your change. Occasionally, a change will be very difficult to test for. In those cases, please include a note in your commit message explaining why.
+
+## Communication
+
+We use [discord](https://www.ory.sh/chat). You are welcome to drop in and ask questions, discuss bugs, etc.
+
+## Conduct
+
+Whether you are a regular contributor or a newcomer, we care about making this community a safe place for you and we've got your back.
+
+* We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic.
+* Please avoid using nicknames that might detract from a friendly, safe and welcoming environment for all.
+* Be kind and courteous. There is no need to be mean or rude.
+* We will exclude you from interaction if you insult, demean or harass anyone. In particular, we do not tolerate behavior that excludes people in socially marginalized groups.
+* Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made uncomfortable by a community member, please contact one of the channel ops or a member of the ORY Oathkeeper core team immediately.
+* Likewise any spamming, trolling, flaming, baiting or other attention-stealing behaviour is not welcome.
+
+We welcome discussion about creating a welcoming, safe, and productive environment for the community. If you have any questions, feedback, or concerns [please let us know](https://www.ory.sh/chat).

README.md

@@ -1,25 +1,119 @@
-# ORY Oathkeeper
+<h1 align="center"><img src="./docs/images/banner_oathkeeper.png" alt="ORY Oathkeeper - Cloud Native Identity & Access Proxy"></h1>
 
 <h4 align="center">
     <a href="https://discord.gg/PAMQWkr">Chat</a> |
     <a href="https://community.ory.am/">Forums</a> |
     <a href="http://eepurl.com/bKT3N9">Newsletter</a><br/><br/>
-    <a href="https://ory.gitbooks.io/oathkeeper/content/">Developer Guide</a> |
-    <a href="http://docs.oathkeeper.apiary.io/">API Docs</a> |
+    <a href="https://www.ory.sh/docs/2-oathkeeper/">Guide</a> |
+    <a href="https://www.ory.sh/docs/api/oathkeeper">API Docs</a> |
     <a href="https://patreon.com/user?u=4298803">Support us on patreon!</a>
 </h4>
 
-ORY Oathkeeper is an Identity & Access Proxy (IAP) that authorizes HTTP requests based on sets of rules. This proxy integrates with ORY Hydra.
+ORY Oathkeeper is an Identity & Access Proxy (IAP) that authorizes HTTP requests based on sets of rules. The BeyondCorp
+Model is designed by [Google](https://cloud.google.com/beyondcorp/) and secures applications in Zero-Trust networks.
+An Identity & Access Proxy is typically deployed in front of (think API Gateway) web-facing applications and is capable
+of authenticating and optionally authorizing access requests.
 
-This service is in **early access**.
+ORY Oathkeeper is a reverse proxy which evaluates incoming HTTP requests based on a set of rules that are defined
+by administartive users. ORY Oathkeeper is thus capable of:
+
+* Identifying the user and providing the user session in form of a JSON Web Token.
+* Restricting access to certain resources based on a set of rules (Authorization).
+
+We plan to generalize this software and make it compatible with Authentication and Authorization providers. For now,
+this proxy integrates best ORY Hydra. Please file an issue if you would like to see your favorite Auth* provider integrated.
+
+This service is under active development and may introduce breaking changes in future releases.
 
 [![CircleCI](https://circleci.com/gh/ory/oathkeeper.svg?style=shield&circle-token=eb458bf636326d41674141b6bbfa475a39c9db1e)](https://circleci.com/gh/ory/oathkeeper)
+[![Coverage Status](https://coveralls.io/repos/github/ory/oathkeeper/badge.svg?branch=master)](https://coveralls.io/github/ory/oathkeeper?branch=master)
 ![Go Report Card](https://goreportcard.com/badge/github.com/ory/oathkeeper)
 
+---
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+- [Installation](#installation)
+- [Ecosystem](#ecosystem)
+  - [ORY Security Console: Administrative User Interface](#ory-security-console-administrative-user-interface)
+  - [ORY Hydra](#ory-hydra)
+- [Security](#security)
+  - [Disclosing vulnerabilities](#disclosing-vulnerabilities)
+- [Telemetry](#telemetry)
+- [Documentation](#documentation)
+  - [Guide](#guide)
+  - [HTTP API documentation](#http-api-documentation)
+  - [Upgrading and Changelog](#upgrading-and-changelog)
+  - [Command line documentation](#command-line-documentation)
+  - [Develop](#develop)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Installation
 
-The easiest way to install ORY Oathkeeper is using Docker:
+The easiest way to install ORY Oathkeeper is using the [Docker Hub Image](https://hub.docker.com/r/oryd/oathkeeper/):
+
+```
+docker run oryd/oathkeeper:<version> help
+```
+
+## Ecosystem
+
+<a href="https://console.ory.am/auth/login">
+    <img align="right" width="30%" src="docs/images/sec-console.png" alt="ORY Security Console">
+</a>
+
+### ORY Security Console: Administrative User Interface
+
+The [ORY Security Console](https://console.ory.am/auth/login). connects with your existing ORY Hydra and ORY Oathkeeper isntallation and lets you manage and monitor them through an intuitive UI.
+
+### ORY Hydra
+
+ORY Hydra is a hardened OAuth2 and OpenID Connect server optimized for low-latency, high throughput, and low resource consumption. ORY Hydra is not an identity provider (user sign up, user log in, password reset flow), but connects to your existing identity provider through a consent app.
+
+## Security
+
+### Disclosing vulnerabilities
+
+If you think you found a security vulnerability, please refrain from posting it publicly on the forums, the chat, or GitHub
+and send us an email to [[email protected]](mailto:[email protected]) instead.
+
+## Telemetry
+
+ORY Oathkeeper collects summarized, anonymized telemetry which can optionally be turned off. Click [here](https://www.ory.sh/docs/1-hydra/0-tutorial/0-readme) to learn more.
+
+## Documentation
+
+### Guide
+
+The Guide is available [here](https://www.ory.sh/docs/2-oathkeeper/).
+
+### HTTP API documentation
+
+The HTTP API is documented [here](https://www.ory.sh/docs/api/oathkeeper).
+
+### Upgrading and Changelog
+
+New releases might introduce breaking changes. To help you identify and incorporate those changes, we document these
+changes in [UPGRADE.md](./UPGRADE.md) and [CHANGELOG.md](./CHANGELOG.md).
+
+### Command line documentation
+
+Run `oathkeeper -h` or `oathkeeper help`.
+
+### Develop
+
+Developing with ORY Hydra is as easy as:
+
+```
+go get -d -u github.com/ory/oathkeeper
+cd $GOPATH/src/github.com/ory/oathkeeper
+dep ensure
+go test ./...
+```
+
+Then run it with in-memory database:
 
 ```
-docker run oryd/oathkeeper:v0.0.29 help
+DATABASE_URL=memory go run main.go serve all
 ```

UPGRADE.md

@@ -0,0 +1,12 @@
+# Upgrading
+
+Please refer to [CHANGELOG.md](./CHANGELOG.md) for a full list of changes.
+
+The intent of this document is to make migration of breaking changes as easy as possible. Please note that not all
+breaking changes might be included here. Refer to refer to [CHANGELOG.md](./CHANGELOG.md) for a full list of changes
+before finalizing the upgrade process.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->