From f46123cb1324fae9858e1a2e54811c3244ae8a68 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira da Silva <bruno@abstractj.org>
Date: Thu, 4 Apr 2019 11:57:04 -0300
Subject: [PATCH] [KEYCLOAK-9685] Add contributors guidelines to
 keycloak-gatekeeper

---
 CONTRIBUTING.md               | 86 +++++++++++++++++++++++++++++++++++
 README.md                     | 72 ++++++++++++++++++++++-------
 docs/building.md              | 38 ++++++++++++++++
 docs/pull_request_template.md |  3 ++
 docs/tests-development.md     | 12 +++++
 5 files changed, 195 insertions(+), 16 deletions(-)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 docs/building.md
 create mode 100644 docs/pull_request_template.md
 create mode 100644 docs/tests-development.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..d600403
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,86 @@
+# Keycloak Community
+
+Keycloak Gatekeeper is an Open Source adapter to solution to protect non-Java modern Applications and Services.
+
+## Building and working with the codebase
+
+Details for building from source and working with the codebase are provided in the [building and working with the code base](docs/building.md) guide.
+
+## Contributing to Gatekeeper
+
+Gatekeeper is an Open Source community-driven project and we welcome contributions as well as feedback from the community.
+
+We do have a few guidelines in place to help you be successful with your contribution.
+
+Here's a quick checklist for a good PR, more details below:
+
+1. [Keycloak Dev Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev)
+2. A JIRA associated with the PR
+3. One feature/change per PR
+4. One commit per PR
+5. PR rebased on master (`git rebase`, not `git pull`) 
+5. Commit message is prefixed by JIRA number
+6. No changes to code not directly related to your PR
+7. Includes test
+8. Includes documentation
+
+Once you have submitted your PR please monitor it for comments/feedback. We reserve the right to close inactive PRs if
+you do not respond within 2 weeks (bear in mind you can always open a new PR if it is closed due to inactivity).
+
+Also, please remember that we do receive a fairly large amount of PRs and also have code to write ourselves, so we may
+not be able to respond to your PR immediately. The best place to ping us is on the thread you started on the dev mailing list.
+
+### Finding something to work on
+
+If you would like to contribute to Keycloak, but are not sure exactly what to work on, you can find a number of open
+issues that are awaiting contributions in the 
+[Keycloak JIRA](https://issues.jboss.org/projects/KEYCLOAK/versions/12340167).
+
+### Open a discussion on Keycloak Dev Mailing List
+
+As Keycloak is a community-driven project we require contributors to send a description of what they are planning to 
+work on to the [Keycloak Dev Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev).
+
+We recommend starting the discussion prior to submitting your PR. Through the mailing list you can get valuable
+feedback both from the core Keycloak team as well as the wider community.
+
+### Create an issue in Keycloak JIRA
+
+Take your time to write a proper JIRA including a good summary and description. 
+
+Remember this may be the first thing a reviewer of your PR will look at to get an idea of what you are proposing 
+and it will also be used by the community in the future to find about what new features and enhancements are included in 
+new releases.
+
+### Implementing
+
+Details for building from source and working with the codebase are provided in the 
+[building and working with the code base](docs/building.md) guide.
+
+Do not format or refactor code that is not directly related to your contribution. If you do this it will significantly
+increase our effort in reviewing your PR. If you have a strong need to refactor code then submit a separate PR for the
+refactoring.
+
+### Documentation
+
+We require contributions to include relevant documentation. Alongside your PR for code changes, prepare a PR to the [Keycloak Documentation](https://github.com/keycloak/keycloak-documentation).
+
+In the description of your PR include a link to the PR to [Keycloak Documentation](https://github.com/keycloak/keycloak-documentation).
+
+### Submitting your PR
+
+When preparing your PR make sure you have a single commit and your branch is rebased on the master branch from the 
+project repository.
+
+This means use the `git rebase` command and not `git pull` when integrating changes from master to your branch. See
+[Git Documentation](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) for more details.
+
+We require that you squash to a single commit. You can do this with the `git rebase -i HEAD~X` command where X
+is the number of commits you want to squash. See the [Git Documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
+for more details.
+
+The above helps us review your PR and also makes it easier for us to maintain the repository. It is also required by
+our automatic merging process. 
+
+We also require that the commit message is prefixed with the Keycloak JIRA issue number (example commit message 
+"KEYCLOAK-9876 My super cool new feature").
diff --git a/README.md b/README.md
index 64ab3e6..a9d9ce5 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,63 @@
-[![Build Status](https://travis-ci.org/keycloak/keycloak-gatekeeper.svg?branch=master)](https://travis-ci.org/keycloak/keycloak-gatekeeper)
-[![GolangCI](https://golangci.com/badges/github.com/keycloak/keycloak-gatekeeper.svg)](https://golangci.com)
-[![GoDoc](http://godoc.org/github.com/keycloak/keycloak-gatekeeper?status.png)](http://godoc.org/github.com/keycloak/keycloak-gatekeeper)
-[![GitHub version](https://badge.fury.io/gh/keycloak%2Fkeycloak-gatekeeper.svg)](https://badge.fury.io/gh/keycloak%2Fkeycloak-gatekeeper)
-[![Go Report Card](https://goreportcard.com/badge/github.com/keycloak/keycloak-gatekeeper)](https://goreportcard.com/report/github.com/keycloak/keycloak-gatekeeper)
-[![Coverage Status](https://coveralls.io/repos/github/keycloak/keycloak-gatekeeper/badge.svg?branch=master)](https://coveralls.io/github/keycloak/keycloak-gatekeeper?branch=master)
+# Keycloak
 
-### **Keycloak Gatekeeper**
+Keycloak is an Open Source Identity and Access Management solution for modern Applications and Services.
 
-Keycloak Gatekeeper is an adapter which, at the risk of stating the obvious, integrates with the [Keycloak](https://github.com/keycloak/keycloak) authentication service. The Gatekeeper is most happy in the company of Keycloak, but is also able to make friends with other OpenID Connect providers. The service supports both access tokens in browser cookie or bearer tokens.
+This repository contains the source code for the Keycloak Gatekeeper. The Gatekeeper is most happy in the company of Keycloak, but is also able to make friends with other OpenID Connect providers. The service supports both access tokens in browser cookie or bearer tokens.
 
-Reporting security vulnerabilities
-----------------------------------
+## Help and Documentation
+
+* [Documentation](https://www.keycloak.org/documentation.html)
+* [User Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-user) - Mailing list for help and general questions about Keycloak
+* [JIRA](https://issues.jboss.org/projects/KEYCLOAK) - Issue tracker for bugs and feature requests
+
+
+## Reporting Security Vulnerabilities
 
 If you've found a security vulnerability, please look at the [instructions on how to properly report it](http://www.keycloak.org/security.html)
 
-Help and Documentation
-----------------------
 
-* [JIRA](https://issues.jboss.org/projects/KEYCLOAK) - Issue tracker for bugs and feature requests
-* [Documentation](https://www.keycloak.org/docs/latest/securing_apps/index.html#_keycloak_generic_adapter) - User Guide
-* [User Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-user) - Mailing list to ask for help and general questions about Keycloak
-* [Developer Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev) - Mailing list to discuss development of Keycloak
+## Reporting an issue
+
+If you believe you have discovered a defect in Gatekeeper please open an issue in our [Issue Tracker](https://issues.jboss.org/projects/KEYCLOAK).
+Please remember to provide a good summary, description as well as steps to reproduce the issue.
+
+
+## Getting started
+
+To run Gatekeeper download the distribution from our [website](https://www.keycloak.org/downloads.html). Extract it and run:
+
+    ./keycloak-gatekeeper[.exe] 
+
+Alternatively, you can use the Docker image by running:
+
+    docker run -it --rm quay.io/keycloak/keycloak-gatekeeper
+    
+For more details refer to the [Keycloak Documentation](https://www.keycloak.org/documentation.html).
+
+
+## Building from Source
+
+To build from source refer to the [building and working with the code base](docs/building.md) guide.
+
+### Writing Tests
+
+To write tests refer to the [writing tests](docs/tests-development.md) guide.
+
+## Contributing
+
+Before contributing to Gatekeeper please read our [contributing guidelines](CONTRIBUTING.md).
+
+
+## Other Keycloak Projects
+
+* [Keycloak](https://github.com/keycloak/keycloak) - Keycloak Server and Java adapters
+* [Keycloak Documentation](https://github.com/keycloak/keycloak-documentation) - Documentation for Keycloak
+* [Keycloak QuickStarts](https://github.com/keycloak/keycloak-quickstarts) - QuickStarts for getting started with Keycloak
+* [Keycloak Docker](https://github.com/jboss-dockerfiles/keycloak) - Docker images for Keycloak
+* [Keycloak Node.js Connect](https://github.com/keycloak/keycloak-nodejs-connect) - Node.js adapter for Keycloak
+* [Keycloak Node.js Admin Client](https://github.com/keycloak/keycloak-nodejs-admin-client) - Node.js library for Keycloak Admin REST API
+
+
+## License
+
+* [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 0000000..1e4203c
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,38 @@
+## Building from source
+
+Ensure you have Golang 1.11 (or newer) and Git installed
+
+    go -version
+    git --version
+    
+First clone the Gatekeeper repository:
+    
+    git clone https://github.com/keycloak/keycloak-gatekeeper.git
+    cd keycloak-gatekeeper
+    
+To build Gatekeeper run:
+
+    make && make test
+    
+This will compile Go files and package the results into a binary file inside `bin/keycloak-gatekeeper` and run the testsuite. 
+
+To build a distribution run:
+
+    make release
+    
+Once completed you will find distribution archives in the `release` folder.
+
+## Starting Gatekeeper
+
+To start Gatekeeper during development first build as specified above, then run:
+
+    bin/keycloak-gatekeeper
+
+## Working with the codebase
+
+We don't currently enforce a code style in Gatekeeper, because Go already have tools to ensure that code is properly formatted. Before submitting any pull request, please run:
+
+    make format && make lint
+
+If your changes require introducing new dependencies or updating dependency versions please discuss this first on the
+dev mailing list. We do not accept new dependencies to be added lightly, so try to use what is available.
diff --git a/docs/pull_request_template.md b/docs/pull_request_template.md
new file mode 100644
index 0000000..6c0cf1f
--- /dev/null
+++ b/docs/pull_request_template.md
@@ -0,0 +1,3 @@
+<!---
+Please read https://github.com/keycloak/keycloak/blob/master/CONTRIBUTING.md and follow these guidelines when contributing to Keycloak
+-->
diff --git a/docs/tests-development.md b/docs/tests-development.md
new file mode 100644
index 0000000..b35142b
--- /dev/null
+++ b/docs/tests-development.md
@@ -0,0 +1,12 @@
+## Writing tests
+
+When writing tests please follow the same approach as we have taken in the other tests. There are many ways to 
+test software and we have chosen ours, so please appreciate that.
+
+The main tests are provided in files with the suffix `_test.go` and can be executed by running:
+
+    make test
+
+When developing your test depending on the feature or enhancement you are testing you may find it best to add to an
+existing test, or to write a test from scratch. For the latter, we recommend finding another test that is close to what 
+you need and use that as a basis.
-- 
GitLab