docs: reshape wording (#11)

* docs: reshape wording * wording updates and drive-by formatting * readme update * readme updates * update note * update note * update note --------- Co-authored-by: Thomas Greenwood <89459745+addepar-tg@users.noreply.github.com>
Addepar · Oct 16, 2024 · 99659f5 · 99659f5
1 parent bb32653
commit 99659f5
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -78,7 +78,7 @@ Alternatively, if you'd like to use Poetry, clone the repo and use `poetry insta
 
 ### Setup Credentials
 
-Credentials can be set using...
+Credentials can be set using:
 1. Environment variables 
 1. A `.env` file
 1. CLI parameters
@@ -126,7 +126,9 @@ export RF_SLACK_CHANNEL=C0123456789
 
 ### Usage
 
-Here are some examples on how to run RedFlag in batch mode.
+> **Note**: When running RedFlag, output messages will indicate it is retrieving and evaluating commits from Pull Requests (PRs). Typically, commits are made via PRs if you have [branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) or [repository rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) in place. Consequently, once a PR is squashed and merged, it appears as a single commit in the target branch. The terminology used may vary depending on how you choose to run RedFlag, as you can specify `--from` and `--to` commit SHAs or branches.
+
+Here are some examples on how to run RedFlag in batch mode:
 
 ```shell
 # Using branch names:

diff --git a/addepar_redflag/evaluate.py b/addepar_redflag/evaluate.py
@@ -64,7 +64,7 @@ async def review_evaluation(
         'format_instructions': review_parser.get_format_instructions()
     }
 
-    # Check the token count if we pass all files in the PR.
+    # Check the token count if we pass all files in scope
     result.token_count = llm.get_num_tokens(review_prompt.format(**prompt_input))
 
     llm_response = await review_chain \
@@ -75,7 +75,7 @@ async def review_evaluation(
     setattr(result, 'review', llm_response)
 
     prediction = (
-        f'{"Yes, this PR should be tested." if llm_response.result else "No, this PR should not be tested."}\n'
+        f'{"Yes, this should be tested." if llm_response.result else "No, this should not be tested."}\n'
         f'Student Logic: {llm_response.reasoning}'
         f'Relevant Files: {llm_response.files}'
     )
@@ -87,7 +87,7 @@ async def review_evaluation(
         {'additional_information': jira_information, 'format_instructions': ''}
     )
 
-    reference = f'Yes, this PR should be tested. {reference}' if should_review else f'No, this PR should not be tested. {reference}'
+    reference = f'Yes, this should be tested. {reference}' if should_review else f'No, this should not be tested. {reference}'
 
     eval_response = await evaluator.aevaluate_strings(
         input=review_prompt.format(**prompt_input),
@@ -199,7 +199,7 @@ async def do_evaluations(
             total=len(dataset)
         )
 
-    # Retrieve all PRs and corresponding Jira tickets and create tasks
+    # Retrieve all commits and corresponding Jira tickets and create tasks
     task_exception = None
     with progress:
         try:
@@ -224,8 +224,8 @@ async def do_evaluations(
 
                 if jira:
                     result.ticket = get_jira_ticket_from_pr_title(
-                        jira,
-                        pr.title
+                        client=jira,
+                        title=pr.title
                     )
 
                 # Create task
@@ -245,7 +245,7 @@ async def do_evaluations(
                     )
                 )
 
-                # Store PR and Jira information in results list
+                # Store commits and Jira information in results list
                 results.append(result)
 
                 # Update progress bar

diff --git a/addepar_redflag/redflag.py b/addepar_redflag/redflag.py
@@ -85,7 +85,7 @@ async def query_model(
         'format_instructions': review_parser.get_format_instructions(),
     }
 
-    # Check the token count if we pass all files in the PR
+    # Check the token count if we pass all files in scope
     result.token_count = llm.get_num_tokens(review_prompt.format(**prompt_input))
 
     try:
@@ -102,7 +102,7 @@ async def query_model(
         )
         return
 
-    # Only create a test plan if the PR should be reviewed
+    # Only create a test plan if this should be reviewed
     if result.review and result.review.result:
         file_context = (
             build_file_context(result=result, files=result.review.files)
@@ -208,14 +208,14 @@ async def redflag(
         result = Result(pr=pr)
         if jira:
             result.ticket = get_jira_ticket_from_pr_title(
-                jira,
-                pr.title
+                client=jira,
+                title=pr.title
             )
 
         results.append(result)
 
         pretty_print(
-            'Retrieved PRs',
+            'Retrieved commits',
             MessageType.SUCCESS
         )
     else:
@@ -230,7 +230,7 @@ async def redflag(
                 # If we can't find anything, exit
                 if not compare.ahead_by:
                     pretty_print(
-                        'No PRs to evaluate, exiting.',
+                        'Nothing to evaluate, exiting.',
                         MessageType.FATAL
                     )
                     exit(0)
@@ -277,7 +277,7 @@ async def redflag(
             )
 
             progress_task_id = progress.add_task(
-                f'Retrieving {progress_count} PRs',
+                f'Retrieving {progress_count} commits',
                 total=progress_count
             )
 
@@ -333,8 +333,8 @@ async def redflag(
                 result = Result(pr=pr)
                 if jira:
                     result.ticket = get_jira_ticket_from_pr_title(
-                        jira,
-                        title,
+                        client=jira,
+                        title=title,
                         progress=progress
                     )
 
@@ -351,7 +351,7 @@ async def redflag(
                     )
 
         pretty_print(
-            f'Retrieved {progress_count} PRs',
+            f'Retrieved {progress_count} commits',
             MessageType.SUCCESS
         )
 
@@ -388,7 +388,7 @@ async def redflag(
         )
 
         progress_task_id = progress.add_task(
-            'Evaluating PRs',
+            'Evaluating commits',
             total=len(results)
         )
 
@@ -416,7 +416,7 @@ async def redflag(
         exit(1)
 
     pretty_print(
-        'Evaluated PRs',
+        'Evaluated commits',
         MessageType.SUCCESS
     )
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "addepar-redflag"
 version = "1.0.0"
-description = "RedFlag uses AI to identify high-risk code changes. Run it in batch mode for release candidate testing or in CI pipelines to flag PRs and add reviewers. RedFlag's flexible configuration makes it valuable for any team."
+description = "RedFlag uses AI to identify high-risk code changes. Run it in batch mode for release candidate testing or in CI pipelines to flag commits and add reviewers. RedFlag's flexible configuration makes it valuable for any team."
 authors = ["Addepar Security Engineering <security-engineering@addepar.com>"]
 repository = "https://github.com/Addepar/RedFlag"
 license = "MIT"