Merge branch 'main' into joss

Author: xuanxu

app/lib/responder_registry.rb

@@ -93,7 +93,7 @@ def self.available_responders
         responder_class = Object.const_get(name)
         available_responders[responder_class.key] = responder_class
       rescue NameError => err
-        logger.warn("There is a mismatch in a Responder class name/module: #{err.message}")
+        Logger.new(STDOUT).warn("There is a mismatch in a Responder class name/module: #{err.message}")
       end
     end
 

docs/installation.md

@@ -1,17 +1,18 @@
 Installation
 ============
 
-Buffy works listening to events received from GitHub and deciding if/how to reply by passing the received payload to different Responders.
-You can fork Buffy and configure the responders you want to use for any specific repository. There is no need for the Buffy fork to be located in the same GitHub user/organization as the repo where it will be used. To have Buffy ready and listening to events you can install it locally or deploy it to a server or service platform.
-You'll need the following components:
+Buffy functions by monitoring events that are sent from a GitHub repository (e.g., openjournals/joss-reviews). Based on the information in these events, Buffy determines whether and how to respond by passing the event data to different [Responders](https://api.rubyonrails.org/v4.1/classes/ActionController/Responder.html).
 
-- A GitHub user to use as the bot with admin permissions on the target repo (usually a member of the organization owning the repo).
+You can fork Buffy and configure the responders you want to use for a particular repository, and the fork doesn't necessarily
+need to be hosted under the same GitHub user or organization (as the repository where it will be used). For Buffy to be operational, it must be running either through a local installation or deployment to a platform. The following components are necessary for this setup:
+
+- A GitHub user with administrative permissions on the target repository (typically a member of the organization that owns the repository) is required to act as the bot.
 - An instance of Buffy running
-- A webhook configured in the GitHub repo's settings to send events to Buffy
+- A webhook configured in the settings of the GitHub repository that will send events to Buffy (e.g., a `reviews` repository).
 
 ### Create the bot GitHub user
 
-This will be the user responding to commands in the reviews repo.
+This will be the "user" responding to the commands issued from a reviews repository.
 
 **1.** [Sign up at GitHub](https://github.com/join) and create the bot user:
 
@@ -40,13 +41,13 @@ Some applications and services must be available to use by Buffy:
 
 #### Deployment
 
-We will use here [Heroku](https://www.heroku.com) as an example service to deploy Buffy but you can use any other server or platform.
+As an example, we will use [Heroku](https://www.heroku.com) to deploy Buffy. However, any other server or platform can also be used.
 
-**1.** Create a new app in heroku linked to the url of your fork of Buffy. Automatically Heroku will use the `heroku/ruby` buildpack.
+**1.** To begin, create a new app in Heroku linked to the URL of your Buffy fork. Heroku will automatically use the `heroku/ruby` buildpack.
 
-- To process background jobs Buffy needs `redis` installed, several add-ons providing it are available: Heroku Redis, RedisGreen, Redis To Go, etc.
-- To install the `cloc` dependency there's a buildpack for Heroku available [here](https://github.com/openjournals/heroku-buildpack-cloc).
-- Gitinspector can be installed [using npm](https://www.npmjs.com/package/gitinspector). To do so in Heroku, the `heroku/nodejs` buildpack can be added.
+- To process background jobs, Buffy needs a `redis` add-on, such as Heroku Redis or RedisGreen etc.
+- You can use [this Heroku buildpack](https://github.com/openjournals/heroku-buildpack-cloc) to install the `cloc` dependency.
+- You can install Gitinspector using npm by following the instructions [here](https://www.npmjs.com/package/gitinspector). If you plan to deploy to Heroku, you can add the `heroku/nodejs` buildpack to your app.
 
 **2.** In the app settings add the following Config Vars:
 
@@ -64,23 +65,24 @@ We will use here [Heroku](https://www.heroku.com) as an example service to deplo
 
   There are detailed instructions in the Deploy section of your Heroku app.
 
-**4.** You should now have a public URL with Buffy running. You can test that pointing your browser to `/status`, like for example: `https://your-new-buffy-deploy.herokuapp.com/status` It should return a simple *up and running* message.
+**4.** At this point, you should have a public URL pointing to your new Buffy app! To confirm this, you can test it by visiting https://your-new-buffy-deploy.herokuapp.com/status. On success, you should see a basic (*up and running*) message confirming that Buffy is up and running.
 
 
 ### Configure a webhook to send events from GitHub to Buffy
 
-**1.** Go to the settings page of the repository where you want to use buffy. Add a new webhook.
+**1.** Navigate to the settings page of the repository that Buffy will be listening to and add a new webhook.
 
   ![Add webhook](./images/new_webhook.png "Add webhook")
 
-**2.** Configure the new webhook with:
+**2.** Set up the new webhook with the following configuration:
 
         Payload URL: /dispatch path at your public buffy url
         Content type: application/json
         Secret: The BUFFY_GH_SECRET_TOKEN you configured in the previous step
 
   Select individual events to trigger: **issue comments** and **issues**
+  
   ![New webhook](./images/webhook.png "New webhook")
 
 
-If everything went well you should have now your bot responding on the reviews issues. Try `@botname help` for example.
+Assuming everything went smoothly, your Buffy instance should now be responding to review issues. You can test this by sending the `@botname help` command from a reviews issue to verify that the bot is functioning as expected.

docs/responders/github_action.md

@@ -1,7 +1,7 @@
 GitHub Action
 =============
 
-This responder triggers workflow run on a GitHub Action using the GitHub API. Optionally if the call is successful (not the result of the workflow run but the call to trigger it) a reply message can be posted as a comment in the issue.
+This `buffy` responder dispatches an event to trigger a GitHub Action workflow in a repository, where the workflow is defined by a `.github/workflows/*.yaml` file. If desired, upon a successful event dispatch to trigger the workflow (not the outcome of the workflow run), a reply message can be posted as a comment in the (corresponding review) issue.
 Allows [labeling](../labeling).
 
 ## Listens to
@@ -17,7 +17,7 @@ For example, if you configure the command to be _compile pdf_, it will respond t
 
 ## Requirements
 
-Some parameters are required for the responder to work: the `command` to invoke it, and the `workflow_repo` and `workflow_name` values to identify the action to run. All can be set using the settings YAML file.
+Some parameters are required for the responder to work: the `command` to invoke it, and the `workflow_repo` and `workflow_name` values to identify the action to run. All can be set using the respective settings YAML file (e.g., `buffy/config/settings-<environment>.yml`).
 
 ## Settings key
 
@@ -54,22 +54,29 @@ If you want to run multiple responders, use an array of these subparams.
 ## Examples
 
 **A complete example:**
+
+The following snippet sets up `buffy` to react to a `@editorialbot generate pdf` command issued during a `joss` review:
+
 ```yaml
 ...
   github_action:
-    only: editors
-    command: compile pdf
-    description: Generates a PDF based on the paper.md file in the repository
-    workflow_repo: openjournals/reviews
-    workflow_name: compile-pdf.yml
-    inputs:
-      file: paper.md
-    data-from-issue:
-      - branch
-      - target_repository
-    mapping:
-      repository: target_repository
-      number: issue_id
+    - draft_paper:
+        command: generate pdf
+        workflow_repo: openjournals/joss-papers
+        workflow_name: draft-paper.yml
+        workflow_ref: master
+        description: Generates the pdf paper
+        data_from_issue:
+          - branch
+          - target-repository
+          - issue_id
+        mapping:
+          repository_url: target-repository
 ...
 ```
-Once the responder is invoked it triggers the _compile-pdf.yml_ workflow on the _openjournals/reviews_ repository passing to it the _file_, _repository_, _branch_ and _number_ inputs.
+
+Once invoked, this `github_action` responder triggers the [_draft-paper_](https://github.com/openjournals/joss-papers/blob/main/.github/workflows/draft-paper.yml) workflow on the [_openjournals/joss-papers_](https://github.com/openjournals/joss-papers) repository (see the [actions tab](https://github.com/openjournals/joss-papers/actions)). 
+
+The `data_from_issue` field lists the values of _branch_, _target-repository_, and _issue-id_ (which `buffy` fetches from a review issue body) that serve as input arguments for this action. The optional `mapping` field indicates that the value _target-repository_ is mapped to the _repository_url_ variable.
+
+For additional use cases, please refer to the complete [`settings-production.yml`](https://github.com/openjournals/buffy/blob/joss/config/settings-production.yml) file located under the `joss` branch of `buffy`.