Merge pull request #119 from OrkoHunter/add_contributing.md

Add CONTRIBUTING doc

.github/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to PEP 8 Speaks
+
+:sparkles::tada: First off, thanks for taking the time to contribute! :tada::sparkles:
+
+This guide will help you make changes to PEP 8 Speaks. The [GitHub app](https://github.com/apps/pep8-speaks) is a hosted version which is managed by me.
+Since the source code is public, you can fork, deploy and use it freely. Read [instructions to deploy a fork](https://github.com/OrkoHunter/pep8speaks/wiki/Instructions-to-deploy-a-fork).
+
+
+Table of Contents
+=================
+
+* [Questions](#questions)
+* [Sending a Pull Request](#sending-a-pull-request)
+    * [Run local server](#run-local-server)
+    * [How to test locally](#how-to-test-locally)
+    * [Code style](#code-style)
+* [Documentation](#documentation)
+* [Testing](#testing)
+* [Additional notes](#additional-notes)
+
+
+## Questions
+
+[Create an issue](https://github.com/OrkoHunter/pep8speaks/issues/new) and I will get back to you as soon as I can!
+
+## Sending a Pull Request
+
+### Run local server
+
+Use Python 3.6+ and pip3.
+
+- Fork the repository.
+- Clone your fork.
+- Create a new branch.
+- Install the requirements.
+
+``` shell
+$ pip3 install -r requirements/test.txt
+```
+
+- Start the server
+
+``` shell
+$ python3 server.py
+```
+
+
+
+
+### How to test locally
+
+``` shell
+$ pytest tests/local
+```
+
+These tests do not cover all the source files. The branch will get tested on Travis when the Pull Request is created.
+You can help writing more local unit tests and mock tests. Thanks to [@chinskiy](https://github.com/chinskiy) for bootstrapping the test framework.
+
+### Code style
+
+Please run `flake8` after making your changes to test the coding style.
+
+``` shell
+$ flake8
+```
+
+Have a look at `setup.cfg` for flake8 configurations.
+
+
+## Documentation
+
+> A description of how the project works. Feel free to improve this section or create an issue if more needs to be added.
+
+All the requests sent by GitHub are processed in `server.py` in the root of the repository.
+
+`server.py` then decides what is the type of the request and assigns the appropriate handler function located in `pep8speaks/handlers.py`.
+
+`handlers.py` makes the use of `helpers.py`, `models.py`, `utils.py` and other modules inside `pep8speaks/` to decide what to do with the request.
+
+## Testing
+
+All changes made to the source files have to be submitted via Pull Requests. The test workflow is as follows:
+
+- A Pull Request is created on this repository.
+- The branch of the PR is then deployed as a review app on Heroku.
+  - This process can not be automated for security reasons. Hence, this is done manually by me.
+- A test GitHub app called [test-pep8speaks](https://github.com/apps/test-pep8speaks) is already installed on the repository [OrkoHunter/test-pep8speaks](https://github.com/OrkoHunter/test-pep8speaks).
+- The Payload URL of the test GitHub app is changed to that of the recently deployed review app on Heroku.
+  - This is usually `https://pep8speaks-pr-###-herokuapp.com` where `###` is the PR number.
+- Travis is to be restarted. This ensures that the tests would use the deployed review app as server.
+- We then wait for the sweet green checks! :white_check_mark:
+
+The crucial tests to be run in this process are written inside [tests/test_workflow.py](https://github.com/OrkoHunter/pep8speaks/blob/master/tests/test_workflow.py). The workflow is written in the module and is as follows :
+
+* Each branch on https://github.com/OrkoHunter/test-pep8speaks correspond to a type of test.
+* The test functions create a new branch from the existing branches.
+* The new branches are then used to create a Pull Request on the master branch of the test repository.
+* We then expect [@pep8speaks](https:/github.com/pep8speaks] to make the comment.
+* If the comment is not what we expected for if the bot does not comment at all, the test fails.
+* Finally, the test closes the PR and deletes the branch.
+
+
+**Keywords**
+head: The new branch which is used to create the Pull Request.
+base: The existing branch where the changes are supposed to pulled into.
+sha: sha of the latest commit in the corresponding test branches.
+     Get the list of sha of the repo at
+     https://api.github.com/repos/OrkoHunter/test-pep8speaks/git/refs/heads/
+
+
+
+## Additional notes
+
+- The README and this document is inside the `/.github/` directory.
+- After editing markdown documents, consider updating the Table of Contents. Check out this cool [script](https://github.com/ekalinin/github-markdown-toc/).
+- Check out the following resources to get help.
+  - https://guides.github.com/
+  - https://help.github.com/en/articles/creating-a-pull-request
+
+
+Thanks! :heart: :heart: :heart:

.github/README.md

@@ -1,21 +1,36 @@
-# PEP 8 Speaks [![Build Status](https://travis-ci.org/OrkoHunter/pep8speaks.svg?branch=master)](https://travis-ci.org/OrkoHunter/pep8speaks) ![GitHub contributors](https://img.shields.io/github/contributors/OrkoHunter/pep8speaks.svg) [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/OrkoHunter) [![Donate on liberapay](https://img.shields.io/liberapay/receives/OrkoHunter.svg?logo=liberapay)](https://liberapay.com/OrkoHunter)
+# PEP 8 Speaks [![Build Status](https://travis-ci.org/OrkoHunter/pep8speaks.svg?branch=master)](https://travis-ci.org/OrkoHunter/pep8speaks) ![GitHub release](https://img.shields.io/github/release/OrkoHunter/pep8speaks.svg) ![GitHub contributors](https://img.shields.io/github/contributors/OrkoHunter/pep8speaks.svg) [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/OrkoHunter) [![Donate on liberapay](https://img.shields.io/liberapay/receives/OrkoHunter.svg?logo=liberapay)](https://liberapay.com/OrkoHunter)
 
 
 A GitHub :octocat: app to automatically review Python code style over Pull Requests
 
-<h1 align="center"><img src="logo.png"></h1>
+<p align="center">
+    <img src="logo.png">
+</p>
 
-> "PEP 8 unto thyself, not unto others" - Raymond Hettinger
+Table of Contents
+=================
 
-# Example
-
-<img src="action.gif">
+   * [Installation](#installation)
+   * [Example](#example)
+   * [Main features](#main-features)
+   * [Configuration](#configuration)
+   * [Popular Users](#popular-users)
+   * [Miscellaneous features](#miscellaneous-features)
+   * [Private repos](#private-repos)
+   * [How to fix PEP 8 issues?](#how-to-fix-pep-8-issues)
+   * [Release announcements](#release-announcements)
+   * [Contributing](#contributing)
 
-# How to Use?
+# Installation
 
  - Go to the homepage of the app - https://github.com/apps/pep8-speaks
  - Click on the Configure button
- - Add repositories or organizations to activate PEP8Speaks
+ - Add repositories or organizations to activate PEP 8 Speaks
+
+# Example
+
+<img src="action.gif">
+
 
 # Main features
 
@@ -132,9 +147,11 @@ This app will only work for publicly hosted repositories. So if you are looking
 
 Updates to the app are announced using the GitHub Release feature over [here](https://github.com/OrkoHunter/pep8speaks/releases). A lot of major changes are made as the community grows bigger. Click on `Watch` -> `Releases only` on top of the page, to get notified about new configurations or feature updates.
 
-# Support
+Usually, the master branch is deployed as soon as Pull Requests are merged in the repository. However, on every Friday, I  make a release and make sure the latest code is deployed. You do not need to do anything to use the latest version. If you use a fork of PEP 8 Speaks, check out the Release space.
+
+# Contributing
 
-You can support the project by contributing to its development. If you have any suggestions for new features or improvements, please [create an issue](https://github.com/OrkoHunter/pep8speaks/issues/new). Pull Requests are most welcome ! Also, if you use this project and you like it, [please let me know](https://saythanks.io/to/OrkoHunter) :)
+You can support the project by contributing to its development. If you have any suggestions for new features or improvements, please [create an issue](https://github.com/OrkoHunter/pep8speaks/issues/new). Pull Requests are most welcome ! Read [CONTRIBUTING](/.github/CONTRBUTING.md) doc to understand how the project works and how you can make changes.
 
 The project requires to be hosted on a server and due to which, it needs financial support as well.
 
@@ -144,6 +161,7 @@ Please read the [case for funding PEP 8 Speaks](https://github.com/OrkoHunter/pe
 [![Donate](https://img.shields.io/liberapay/receives/OrkoHunter.svg?logo=liberapay)](https://liberapay.com/OrkoHunter)
 [![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.me/orkohunter)
 
+If you use this project and you like it, [please let me know](https://saythanks.io/to/OrkoHunter). Thanks!
 
 :heart:
 

.github/auto-comment.yml

@@ -8,4 +8,4 @@ pullRequestOpened: >
 
   @OrkoHunter Create a review app for this PR on Heroku and  update the `Webhook URL` of the [test-pep8speaks app](https://github.com/settings/apps/test-pep8speaks). Finally restart Travis to test this PR.
 
-  Remember to redeploy the production app and revert the Webhook URL when the Pull Request is merged.
+  Remember to deploy the production app and revert the Webhook URL of the test GitHub app when the Pull Request is merged.

Procfile

@@ -1 +1 @@
-web: gunicorn app:app
+web: gunicorn server:app

conftest.py

@@ -1,5 +1,7 @@
+"""Fixture configuration for pytest."""
 import pytest
-from app import create_app
+
+from server import create_app
 
 
 @pytest.fixture

requirements/test.txt

@@ -1,4 +1,4 @@
 -r base.txt
 pytest==3.2.2
 pytest-flask==0.10.0
-pytest-mock==1.6.3
+pytest-mock==1.6.3