updated README files to reflect current state of Kebechet

README.md

@@ -3,23 +3,96 @@ Kebechet
 
 > I'm Kebechet, goddess of freshness. I will keep your sources and dependencies fresh and up-to-date.
 
-Kebechet is a SourceOps bot that automates updating dependencies of your project. Currently, it supports managing and updating Python projects based on [pipenv](https://docs.pipenv.org/) files (`Pipfile` and `Pipfile.lock`) or `requirements.txt`/`requirements.in` files (see [pip-tools](https://pypi.org/project/pip-tools/) - Kebechet is a replacement for it)
-
-Configuration of Kebechet
--------------------------
-
-Kebechet is configured using a simple YAML configuration file. Check documentation of managers to get all the available options.
-
-Each configuration entry configures a manager. Please check [managers and examples](https://github.com/thoth-station/kebechet/tree/master/kebechet/managers) to get info about configuration options.
-
-The YAML configuration file can be supplied directly as a path to a file on filesystem as well as a URL to a file - handy for managing configuration of your Kebechet deployment in a Git repository (you have to supply a URL to a raw YAML configuration file).
-
-Managers
---------
-
-Kebechet consists of managers that perform certain actions.
-
-A list of managers with their configuration (documentation lives in the manger directory) can be found [in the repo](https://github.com/thoth-station/kebechet/tree/master/kebechet/managers).
+Kebechet is a SourceOps bot that automates updating dependencies of your project. Currently, it supports managing and
+updating Python projects based on [pipenv](https://docs.pipenv.org/) files (`Pipfile` and `Pipfile.lock`) or
+`requirements.txt`/`requirements.in` files (see [pip-tools](https://pypi.org/project/pip-tools/) - Kebechet is a
+replacement for it).
+
+Kebechet is many bots masking themselves as a single bot.  The main rationale behind the creation of Kebechet was that
+it should be able to do simple repetitive actions, providing value by updating dependencies, tagging new versions, etc.
+Adding a new action should be "easy", a new manager can interact with the GitHub, GitLab, or Pagure APIs using
+[packit/ogr](https://github.com/packit/ogr) and interact with git using
+[GitPython](https://gitpython.readthedocs.io/en/stable/).
+
+For a full list of managers go [here](kebechet/managers/README.rst).
+
+User Guide
+----------
+
+### Configuration
+
+To start using Kebechet you should begin by creating a configuration file in the root of your repository, this
+configuration file should have the name `.thoth.yaml`. This configuration file can contain other Thoth based
+configuration, but for our purposes we will focus only on the aspects which pertain to Kebechet. Below is an example of
+the `.thoth.yaml` file found in this repository:
+
+```yaml
+host: khemenu.thoth-station.ninja
+tls_verify: false
+requirements_format: pipenv
+
+runtime_environments:
+  - name: rhel:8
+    operating_system:
+      name: rhel
+      version: "8"
+    python_version: "3.8"
+    recommendation_type: latest
+
+managers:
+  - name: pipfile-requirements
+  - name: update
+    configuration:
+      labels: [bot]
+  - name: info
+  - name: version
+    configuration:
+      maintainers:
+        - sesheta
+        - goern
+        - fridex
+      assignees:
+        - sesheta
+      labels: [bot]
+      changelog_file: true
+```
+
+To start you only need to define the managers section:
+
+```yaml
+...
+managers:
+  - name: pipfile-requirements
+  - name: update
+    configuration:
+      labels: [bot]
+  - name: info
+  - name: version
+    configuration:
+      maintainers:
+        - sesheta
+        - goern
+        - fridex
+      assignees:
+        - sesheta
+      labels: [bot]
+      changelog_file: true
+...
+```
+
+Each entry of managers corresponds with a manager defined in Kebechet. A mapping from names to managers can be found in
+the `__init__.py` file of `kebechet.managers` under [REGISTERED_MANAGERS](kebechet/managers/__init__.py). Manager
+configuration is a list of key-value pairs which can be used to configure individual managers; individual manager
+configuration can be found in each of their [READMEs](kebechet/managers/README.rst).
+
+### Bot Installation
+
+Once you have created a configuration file in your repository, you are ready to install the bot. Thoth only supports a
+GitHub bot at this time. To install it, visit [this](https://github.com/marketplace/khebhut) link and install it for all
+repos which you have created configuration for. After you have done this, Kebechet should be installed on your repo and
+making contributions.
+
+If you need to run Kebechet on a different service, take a look at [deploying Kebechet](#deploying-kebechet)
 
 Issues created by Kebechet
 --------------------------
@@ -33,30 +106,40 @@ Bot updates pull requests and issues and notifies about updates via comments (to
 
 This is especially helpful for example if you have failing updates of your dependency and you would like to keep the pull request opened and check for fix later. Setting 'silent-bot' label to the PR will suppress Kebechet to post updates and you will not retrieve spam messages anymore.
 
-Notes
------
-
-To issue an update to Git repository, Kebechet creates branches in the provided repository.
-
 Deploying Kebechet
 ------------------
 
-To deploy Kebechet on an OpenShift cluster use kustomize and the [Thoth Application template files](https://github.com/thoth-station/thoth-application/tree/master/kebechet). Please ensure all the input parameters are correctly set for each of the templates.
+To deploy Kebechet on an OpenShift cluster use kustomize and the [Thoth Application template
+files](https://github.com/thoth-station/thoth-application/tree/master/kebechet). Please ensure all the input parameters
+are correctly set for each of the templates.
 
-If Kebechet finds the env variables, `GITHUB_APP_ID` and `GITHUB_PRIVATE_KEY_PATH`, it is going to authenticate as a Github Application.
+If Kebechet finds the env variables, `GITHUB_APP_ID` and `GITHUB_PRIVATE_KEY_PATH`, it is going to authenticate as a
+Github Application.
 
-Otherwise its going to fallback to look for an OAuth token to authenticate for an successful run. In both cases the SSH key is needed to commit code changes.
+Otherwise its going to fallback to look for an OAuth token to authenticate for an successful run. For GitLab and Pagure,
+OAuth tokens are the only autentication method for the API. The OAuth token the application looks for is dependent on
+the service type it is being run on, the form of the token will look like so, `<GITHUB|GITLAB|PAGURE>_KEBECHET_TOKEN`.
+
+In all cases the SSH key is needed to commit code changes.
 
 Running Kebechet Locally for Development
 ----------------------------------------
 
-This guide is specific to GitHub. To run locally you need to [create a personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)%20on%20GitHub%20and%20add%20it%20to) your envvars (`$ export GITHUB_KEBECHET_TOKEN=<your-token>`). Then all you need to do is run the Kebechet-CLI in the virtual environment generated by pipenv by running either:
+This guide is specific to GitHub. To run locally you need to [create a personal access
+token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+on GitHub and add it to) your envvars (`$ export GITHUB_KEBECHET_TOKEN=<your-token>`). Then all you need to do is run
+the Kebechet-CLI in the virtual environment generated by pipenv by running either:
 
-1.  `$ pipenv run PYTHON_PATH=. kebechet-cli run-url -u <url-to-github-repo> -s <service-type>`
-2.  `$ PYTHON_PATH=. kebechet-cli run-url -u <url-to-github-repo> -s <service-type>`
+1. `$ pipenv run PYTHON_PATH=. kebechet-cli run-url -u <url-to-github-repo> -s <service-type>`
+1. `$ PYTHON_PATH=. kebechet-cli run-url -u <url-to-github-repo> -s <service-type>`
 
 where \<service-type\> is GITHUB
 
 This assumes you have a repository with proper configuration files and is ready for Kebechet to manage. For a very minimal repo see [here](<https://github.com/KPostOffice/khebhut_test>)
 
 This guide can also be used to interact with GitLab and Pagure, the only difference being that the token must be generated for the specifice service, service-type should be GITLAB or PAGURE and the token env var should be \<service-type\>\_KEBECHET\_TOKEN
+
+Notes
+-----
+
+To issue an update to Git repository, Kebechet creates branches in the provided repository.

kebechet/managers/README.rst

@@ -1,8 +1,25 @@
 Kebechet Managers
 -----------------
 
-This submodule states all the available managers in Kebechet. See each manager's submodule to get all available options
-each manager provides for you.
+Available Managers
+==================
+
+* `Info Manager`_
+* `Label Bot Manager`_
+* `Pipfile Requirements Manager`_
+* `Thoth Advise Manager`_
+* `Thoth Provenance Manager`_
+* `Update Manager`_
+* `Version Manager`_
+
+.. _`Info Manager`: info/README.rst
+.. _`Label Bot Manager`: label_bot/README.rst
+.. _`Pipfile Requirements Manager`: pipfile_requirements/README.rst
+.. _`Thoth Advise Manager`: thoth_advise/README.rst
+.. _`Thoth Provenance Manager`: thoth_provenance/README.rst
+.. _`Update Manager`: update/README.rst
+.. _`Version Manager`: version/README.rst
+
 
 Developing your own manager
 ===========================
@@ -29,16 +46,16 @@ If you wish to operate on repository source code, you can request to clone it:
 
         from kebechet.utils import cloned_repo
 
-        with cloned_repo(self.service_url, self.slug) as repo:
+        with cloned_repo(self.service_url, self.slug, branch="my_branch") as repo:
             with open('my_file.txt', 'w') as my_file:
                 my_file.write("Hello, Kebechet!")
 
             repo.git.add(my_file)
             repo.git.push()
 
 The last thing you need to do, is to register your manager to `REGISTERED_MANAGERS` constant (you can find it in
-`kebechet/managers/__init__.py` file) so Kebechet knows about your manager. Manager can be referenced by its name in
-lowercase (class name without the "manager" suffix).
+`kebechet/managers/__init__.py` file) so that the mapping can be used for configuration. Best practice is to remove the
+Manager suffix from the class name, convert to lowercase and put "-" between each word.
 
 Overlays
 ========

kebechet/managers/info/README.rst

@@ -11,17 +11,11 @@ An example of configuration for this manager:
 
 .. code-block:: yaml
 
-  repositories:
-    - slug: thoth-station/kebechet
-      # State token explicitly or let it expand from env vars:
-      token: '{SECRET_TOKEN_IN_ENV}'
-      service_type: github  # or gitlab
-      # Optionally for self-hosted services:
-      # service_url: <URL>
-      # tls_verify: true/false
-      managers:
-        - name: info
-          # This manager has no configuration.
+  managers:
+    ...
+    - name: info
+      # This manager has no configuration.
+    ...
 
 An example of this manager in action can be found in `this issue <https://github.com/thoth-station/kebechet/issues/96>`_.
 

kebechet/managers/label_bot/README.rst

@@ -2,7 +2,7 @@ Kebechet Label Bot Manager
 -------------------------------------
 
 This manager will help label issues in your repositories powered by AI based model Roberta.
-Find more about the model powering this manager `here <https://github.com/thoth-station/Github-Issues-Classifier>`_.
+Find more about the model powering this manager `here <https://github.com/thoth-station/Github-Issues-Classifier>`__.
 
 Developer Note - Ensure Kebechet points to the API Url with help of the environment variable - `LABELBOT_URL`
 For example local dev - `LABELBOT_URL = "http://localhost:8888"`
@@ -14,11 +14,13 @@ An example configuration:
 
 .. code-block:: yaml
 
+    ...
     managers:
       - name: label-bot
+        # This manager has no configuration.
+    ...
 
-
-An example of this version manager in action can be found `here <https://github.com/saisankargochhayat/kebechet_sample/issues/140>`_.
+An example of this version manager in action can be found `here <https://github.com/saisankargochhayat/kebechet_sample/issues/140>`__.
 
 Manager Author
 ==============

kebechet/managers/pipfile_requirements/README.rst

@@ -14,21 +14,15 @@ An example configuration:
 
 .. code-block:: yaml
 
-    repositories:
-    - slug: thoth-station/kebechet
-      # State token explicitly or let it expand from env vars:
-      token: '{SECRET_TOKEN_IN_ENV}'
-      service_type: github  # or gitlab
-      # Optionally for self-hosted services:
-      # service_url: <URL>
-      # tls_verify: true/false
-      managers:
-        - name: pipfile-requirements
-          configuration:
-            # Set to true if you would like to state fully pinned down software stack of your application.
-            lockfile: true  # Defaults to false.
-
-An example of this version manager in action can be found `here <https://github.com/thoth-station/kebechet/issues/404>`_.
+    ...
+    managers:
+      - name: pipfile-requirements
+        configuration:
+          # Set to true if you would like to state fully pinned down software stack of your application.
+          lockfile: true  # Defaults to false.
+    ...
+
+An example of this version manager in action can be found `here <https://github.com/thoth-station/kebechet/issues/404>`__.
 
 Manager Author
 ==============

kebechet/managers/thoth_advise/README.rst

@@ -1,37 +1,30 @@
 Kebechet Advise-Results Manager
------------------------
+-------------------------------
 This manager will manage your Python dependencies using Thoths recommendation system. Your repository will be automatically updated with the optimal Python packages for your project without you having to lift your finger.
 
 A prerequisite for this manager is to have Pipfile and .thoth.yaml, present in the repo. Pipfile should state all direct dependencies (with possible required specifications). .thoth.yaml should contain a valid configuration for thamos
 
-    Pipfile - respecting _`pipenv <https://pipenv.readthedocs.io/en/latest/advanced/#specifying-package-indexes>`_ tool
+    Pipfile - respecting `pipenv <https://pipenv.readthedocs.io/en/latest/advanced/#specifying-package-indexes>`__ tool
     Pipfile.lock - automatically managed by this manager - states all pinned down versions of your application stack
 
 If you do not have Pipfile.lock present in your repository, this manager will automatically open a pull request with initial dependency lock.
 
-Custom PyPI indexes are supported respecting _`Pipfile <https://pipenv.readthedocs.io/en/latest/advanced/#specifying-package-indexes>`_ syntax.
+Custom PyPI indexes are supported respecting `Pipfile <https://pipenv.readthedocs.io/en/latest/advanced/#specifying-package-indexes>`__ syntax.
 
 If there is any issue in your application stack, the Thamos-Advise manager will open an issue with all the info and will try to resolve issue for you if possible by opening a pull request for you.
 
 Why should I pin down dependencies in my application?
 =====================================================
 Check `this StackOverflow thread <https://stackoverflow.com/questions/28509481>`__.
 
-Options
-=======
-`labels`: specify the labels associated with pull requests and issues
-
 Example
 =======
 
 An example configuration for thoth `.thoth.yaml`
 
-NOTE: This configuration file should be in the root directory of your repository
-
 .. code-block:: yaml
 
   host: {THOTH_SERVICE_HOST}
-  tls_verify: true
   requirements_format: pipenv
 
   runtime_environments:
@@ -50,9 +43,12 @@ NOTE: This configuration file should be in the root directory of your repository
   managers:
     - name: thoth-advise
       configuration:
-        labels: [bot, kebechet]
+        labels: [bot, kebechet]  # these are the labels added to PRs and issues opened by this manager
+
 
-A more detailed description of `thamos` can be found `here <https://github.com/thoth-station/thamos>`_
+Because this manager uses more of Thoth's services, a runtime environment, host and requirements format should be
+defined in the configuration file. More information about configuration options for .thoth.yaml can be found `in the
+thoth-station/thamos repository <https://github.com/thoth-station/thamos>`__.
 
 Manager Author
 ==============