--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.rst	Mon Aug 22 20:38:06 2016 +0800
@@ -0,0 +1,104 @@
+.. image:: https://candolint.dwimlabs.net/bitbucket.org/av6/candolint/status.svg
+    :target: https://candolint.dwimlabs.net/bitbucket.org/av6/candolint
+    :alt: Lint Status
+
+
+Project configuration
+=====================
+
+Here's an example similar to `candolint.yml` of this project itself:
+
+.. code:: yaml
+
+    # bootstrapping data, optional
+    url: https://bitbucket.org/av6/candolint
+    scm: hg
+
+    # linter config, required
+    linters:
+      - name: flake8
+        vars:
+          python_version: 2
+        include:
+          - '**.py'
+
+      - name: yamllint
+        include:
+          - '**.yaml'
+          - '**.yml'
+
+      - name: jshint
+        flags: ['--extract', 'always']
+        include:
+          - '**.html'
+
+
+Bootstrapping data
+------------------
+
+This is the two most basic things needed to check out project source code: its
+URL and SCM.
+
+If you use push hooks or polling, this data is already present in the payload.
+You only need to put it in `projects/<name>.yml` file on the worker if you want
+to run checks manually (e.g. for testing).
+
+
+Linter configuration
+--------------------
+
+This is the list of linters to run on project source code. Each item only
+requires two parameters:
+
+- ``name``: determines what configuration file from `linters/*.yml` will be
+  used (often named after the actual executable)
+- ``include``: a sequence of file patterns for checking
+
+Optional parameters include:
+
+- ``vars``: variables used for installing and running linters (e.g.
+  ``python_version``)
+- ``codes``: allowed exit codes (by default ``0`` and ``1`` are allowed); note
+  that this is only for the actual checking, so if `linter --version` exits
+  with code ``1``, it's considered a failure
+- ``exclude``: a sequence of file patterns to exclude from checks
+- ``flags``: additional command line flags passed to the linter (before passing
+  file path)
+- ``post_flags``: like ``flags``, but passed after file path
+
+The exact base command executed for each linter is specified in `linters/*.yml`
+and cannot be modified in project configuration file, see the next section.
+
+
+Base linter configuration
+=========================
+
+Every linter needs to be configured via `linters/*.yml` file. Some files are
+already there, they are used to check various projects, including this one
+itself. Here's what they look like:
+
+.. code:: yaml
+
+    vars:
+      python_version: 2
+
+    setup:
+      - ['virtualenv', '--python=python%(python_version)s', '../venv%(python_version)s']
+      - ['../venv%(python_version)s/bin/pip', 'install', 'flake8', 'pep8-naming']
+
+    exec: ['../venv%(python_version)s/bin/flake8']
+    version: ['--version']
+
+Required parameters:
+
+- ``exec``: a list of strings that will be fed to `subprocess.Popen` for
+  running this linter
+- ``version``: a list of strings that will be used as command line flags for
+  testing that this linter works after installation
+
+Optional parameters:
+
+- ``setup``: a list of commands (as lists of strings), each will be executed
+  consecutively to install this linter
+- ``vars``: default values for variables, these can be tweaked in project
+  configuration file