docs: corrections and completions and alignments (#752)

Co-authored-by: casaqori <[email protected]>

README.md

@@ -25,6 +25,7 @@ Some examples of what you can do:
 - Ensure pull requests follow conventions and [prevent merging][comment-if-guidelines-not-met] when it is not followed.
 - [Notify author of failed guidelines][comment] when opening an issue.
 - Schedule [detection for obsolete (stale) issues and pull requests][staleness] and notify author and collaborators.
+- [Auto-merge][automerge] pull requests once all checks pass.
 - And [more][configuration]
 
 ---
@@ -45,7 +46,7 @@ We need your help:
 - Have an **💡idea** for a **new feature**? Please [create a new issue](https://github.com/mergeability/mergeable/issues) and tell us!
 - **Fix a bug**, implement a new **validator** or **action** and [open a pull request](CONTRIBUTING.md)!
 
-> ☝️ **NOTE:** For development and testing. You'll want to [read about how to run it locally](deploy.md#running-locally).
+> ☝️ **NOTE:** For development and testing. You'll want to [read about how to run it locally][run-locally].
 
 
 # Authors
@@ -58,4 +59,6 @@ AGPL, Copyright (c) 2019 [Justin Law](https://github.com/jusx) & [Shine Lee](htt
 [comment-if-guidelines-not-met]: https://mergeable.readthedocs.io/en/latest/recipes.html#comment-if-guidelines-not-met
 [comment]: https://mergeable.readthedocs.io/en/latest/actions/comment.html
 [staleness]: https://mergeable.readthedocs.io/en/latest/recipes.html#check-stale-pr-and-issues
+[automerge]: https://mergeable.readthedocs.io/en/latest/recipes.html#auto-merge-pull-requests-once-all-checks-pass
 [configuration]: https://mergeable.readthedocs.io/en/latest/configuration.html
+[run-locally]: https://mergeable.readthedocs.io/en/latest/deployment.html#running-locally

docs/annotations.rst

@@ -1,22 +1,23 @@
+.. _annotations-page:
 Annotations
 =====================================
 
 Annotations allows the use of dynamic values in your recipes.
 
-To bypass the annotation, use `\` prefix. (i.e `\@author` will be replaced with literal `@author`)
+To bypass the annotation, use ``\`` prefix. (i.e ``\@author`` will be replaced with literal `@author`)
 
 ::
+
    @author : replace with the login of creator of issues/PR
 
-Actions supported
 
-- assign
-- comment
-- checks
+Actions supported:
+::
 
+    'assign', 'comment', 'checks'
 
 
-.. note::
-    Don't see any annotation that fits your needs? let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_
+.. hint::
+    Don't see any annotation that fits your needs? Let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_ on github.
 
 

docs/configuration.rst

@@ -7,8 +7,8 @@ Configuration
 
 First, you'll need to start by creating a ``.github/mergeable.yml`` file in your repository.
 
-.. hint::
-  Check out our :ref:`recipes-page` page for examples and most commonly used settings
+.. note::
+  Check out our :ref:`recipes-page` page for examples and most commonly used settings.
 
 Next, we'll go into how the configuration is structured.
 
@@ -34,7 +34,7 @@ error:
 
 Each recipe appears as a separate check in the pull request.
 
-Here is a full example of how a recipe looks -
+Here is a full example of how a recipe looks:
 
 .. code-block:: yml
 
@@ -79,7 +79,7 @@ Here is a full example of how a recipe looks -
           - do: {{action}}
 
 .. note::
-    There are some default actions that'll be automatically applied based on the events specified
+    There are some default actions that'll be automatically applied based on the events specified.
 
 Filters
 ------------
@@ -90,7 +90,7 @@ Filters are checks that mergeable will process in order to determine if validato
     Each filter have certain events that it can support, so keep an eye out for them.
 
 .. hint::
-    Don't see an filter that should be on here? Let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_ on github
+    Don't see an filter that should be on here? Let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_ on github.
 
 Filter List
 
@@ -108,7 +108,7 @@ Validators are checks that mergeable will process in order to determine whether
     Each validator have certain events that it can support, so keep an eye out for them.
 
 .. hint::
-    Don't see an validator that should be on here? Let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_ on github
+    Don't see an validator that should be on here? Let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_ on github.
 
 Validator List
 
@@ -125,6 +125,7 @@ Validator List
     validators/description.rst
     validators/headRef.rst
     validators/label.rst
+    validators/lastComment.rst
     validators/milestone.rst
     validators/project.rst
     validators/size.rst
@@ -153,7 +154,7 @@ Options List
 Operators
 ------------
 
-These operators can help create more complex logic of validations
+These operators can help create more complex logic of validations.
 
 Operator List
 
@@ -169,7 +170,7 @@ Actions
 Actions that mergeable is currently able to perform.
 
 .. hint::
-    Don't see an action that should be on here? Let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_ on github
+    Don't see an action that should be on here? Let us know by creating an `issue <https://github.com/mergeability/mergeable/issues/new>`_ on github.
 
 .. toctree::
     actions/assign.rst
@@ -185,9 +186,10 @@ Actions that mergeable is currently able to perform.
 Reusable Configuration
 --------------------------
 
-YML has a feature called `Anchor<https://blog.daemonl.com/2016/02/yaml.html>`_ that allows you to create reusable parts in the config
+YML has a feature called `Anchor <https://blog.daemonl.com/2016/02/yaml.html>`_ that allows you to create reusable parts in the config:
 
 .. code-block:: yml
+
     on_fail_comment: &default_fail_comment
       - do: comment
         payload:

docs/deployment.rst

@@ -4,50 +4,56 @@ Deploying
 ---------------------
 If you would like to run your own instance of this plugin, you can do so by forking this repo and deploying it to your own servers or run it locally
 
-The `Probot deployment guide <https://probot.github.io/docs/deployment/>`_ describes this as well
+The `Probot deployment guide <https://probot.github.io/docs/deployment/>`_ describes this as well.
 
 `Create a GitHub App <https://github.com/settings/apps/new>`_ and configure the permissions & events with the following:
 
 **Settings:**
 
 * GitHub app name - **Your app name**
-* Webhook URL - **Your webhook url for listening to events** (for local deployments you can use `smee.io <https://smee.io/>`_))
+* Webhook URL - **Your webhook url for listening to events** (for local deployments you can use `smee.io <https://smee.io/>`_)
 * Webhook secret - **Your generated webhook seceret** (GitHub app page has instructions on how to create this)
 
-**Permissions:**
+**Repository Permissions:**
 
 * Checks - **Read & Write**
 * Issues - **Read & Write**
-* Repository metadata - **Read Only**
-* Pull requests - **Read Only**
-* Commit Statuses - **Read & Write**
-* Single File - **Read-only**
+* Metadata - **Read Only**
+* Pull requests - **Read & Write**
+* Commit statuses - **Read & Write**
+* Single file - **Read-only**
   * Path: ``.github/mergeable.yml``
-* Repository Contents - **Read-Only**
-* Repository projects - **Read-Only**
+* Contents - **Read-Only**
+* Projects - **Read-Only**
+
+**Organization Permissions:**
+
+* Members - **Read Only**
 
 **And subscription to the following events:**
 
+* [x] Issue comment
+* [x] Issues
 * [x] Pull request
-* [x] Pull request review comment
 * [x] Pull request review
-* [x] Issues
+* [x] Status
 
 Make sure to create a private key for the app after it's been registered.
 
 Running Locally
 ------------------
 
-1. Clone the forked repository on to your machine
+1. Clone the forked repository on to your machine.
 2. Globally install smee-client from with npm ``npm install -g smee-client``
 3. Go to `smee.io <https://smee.io>`_ and create a new webhook OR use the cli by
    running the ``smee`` command.
 4. Copy ``.env.template`` to a new file called ``.env``, and fill it out.
-5. Run ``npm run dev`` in your local repository
+5. Run ``npm run dev`` in your local repository.
 6. Add a repository for your Github app by going to `application settings <https://github.com/settings/installations>`_
-7. Do a test pull request to check if everything is working
+7. Do a test pull request to check if everything is working.
 
-Note: if you wish to use a different config file name besides ``mergeable.yml``, use the ``CONFIG_PATH`` environment variable. Config files use ``.github`` as base path, see `here <https://github.com/probot/probot/blob/master/src/context.ts#L230>`_.
+.. note::
+    If you wish to use a different config file name besides ``mergeable.yml``, use the ``CONFIG_PATH`` environment variable. Config files use ``.github`` as base path, see `here <https://github.com/probot/probot/blob/master/src/context.ts#L230>`_.
 
 
 Possible Issues
@@ -59,6 +65,13 @@ This happens when you haven't configured the webhook secret correctly in your
 locally running instance. Make sure to set the ``SECRET_TOKEN`` environment variable
 in ``.env`` before running ``npm run dev``.
 
+``ERROR probot: Integration not found``
+
+This may occur when running Mergeable using a GitHub Enterpise instance.
+
+To fix, try making sure you've set the `GHE_HOST` variable in `.env` to the
+hostname of your Enterprise instance. E.g. `GHE_HOST=github.your_company.com`.
+
 .. note::
     For a list of possible configurable variables within mergeable, check :ref:`configurable-variables-page`
 

docs/filters/payload.rst

@@ -1,9 +1,9 @@
 Payload
 ^^^^^^^^^^^^^^
 
-Check against any available fields within the payload, each event can have different field, please refer to `github API documentation<https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads>`_ for available fields.
+Check against any available fields within the payload, each event can have different field, please refer to `github API documentation <https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads>`_ for available fields.
 
-An example to check if a pull_request_review event has `state` of `changes_requested`
+An example to check if a `pull_request_review` event has ``state`` of `changes_requested`
 
 ::
 
@@ -23,7 +23,7 @@ To check if a `pull_request` event is not a `draft`
             boolean:
               match: false
 
-An example to check if a pull_request event has a `label` named `foo`
+An example to check if a `pull_request` event has a ``label`` named `foo`
 
 ::
 
@@ -54,4 +54,4 @@ Each field must be checked using one of the following options
 Supported Events:
 ::
 
-    'pull_request.*', 'pull_request_review.*', 'issues.*'
+    'pull_request.*', 'pull_request_review.*', 'issues.*', 'issue_comment.*'

docs/index.rst

@@ -14,6 +14,7 @@ Mergeable helps automate your team's GitHub workflow without a single line of co
    usage.rst
    configuration.rst
    recipes.rst
+   deployment.rst
    contributing.rst
    support.rst
    changelog.rst

docs/options/must_exclude.rst

@@ -45,7 +45,7 @@ You can also use an array of regex matchers. If any of them match, the validatio
      - No
      - i
 
-Supported Validators:-
+Supported Validators:
 ::
 
-    'baseRef', 'headRef', 'changeset', 'content', 'description', 'label', 'milestone', 'title'
+    'author', 'baseRef', 'headRef', 'changeset', 'content', 'description', 'label', 'lastComment', 'milestone', 'title'

docs/options/must_include.rst

@@ -45,7 +45,7 @@ You can also use an array of regex matchers. If any of them match, the validatio
      - No
      - i
 
-Supported Validators:-
+Supported Validators:
 ::
 
-    'baseRef', 'headRef', 'changeset', 'commit', 'content', 'description', 'label', 'milestone', 'project', 'title'
+    'author', 'baseRef', 'headRef', 'changeset', 'commit', 'content', 'description', 'label', 'lastComment', 'milestone', 'project', 'title'

docs/recipes.rst

@@ -3,9 +3,12 @@
 Recipes
 --------------------------
 
+.. note::
+  Check out our :ref:`annotations-page` page for possible placeholders in values.
+
 Work In Progress
 """""""""""""""""
-Prevent accidental merging of Pull Requests that are work in progress by labeling it WIP or prefixing the title with the abbreviation.
+Prevent accidental merging of Pull Requests that are work in progress by labeling it `WIP` or prefixing the title with the abbreviation.
 
 ::
 
@@ -18,7 +21,7 @@ Prevent accidental merging of Pull Requests that are work in progress by labelin
               regex: ^\[WIP\]
           - do: label
             must_exclude:
-              regex: 'wip'
+              regex: 'wip|work in progress'
 
 No Empty Description
 """""""""""""""""

docs/validators/size.rst

@@ -14,7 +14,7 @@ Validates that the files specified are all part of a pull request (added or modi
         count: 250
         message: Change is very large. Should be under 250 lines of additions
       deletions:
-        count: 500
+        count: 250
         message: Change is very large. Should be under 250 lines of deletions.
       ignore_comments: false #if true, comments will not be counted toward the lines count