Merge pull request #11 from github/summary-metrics

Add summary metrics table to markdown output
github · Oct 11, 2023 · b0fa976 · b0fa976
2 parents cfe4170 + 8338638
commit b0fa976
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,11 @@
 # Contributors action
+
 [![Python package](https://github.com/github/contributors/actions/workflows/python-ci.yml/badge.svg)](https://github.com/github/contributors/actions/workflows/python-ci.yml) [![Docker Image CI](https://github.com/github/contributors/actions/workflows/docker-ci.yml/badge.svg)](https://github.com/github/contributors/actions/workflows/docker-ci.yml) [![CodeQL](https://github.com/github/contributors/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/github/contributors/actions/workflows/github-code-scanning/codeql)
 
 This is a GitHub Action that given an organization or repository, produces information about the contributors over the specified time period (if specified).
 
 Similar actions to help you recognize contributors by putting them into a `README` or `CONTRIBUTORS.md` include:
+
 - [contributor-list](https://github.com/marketplace/actions/contribute-list)
 
 This action was developed by the GitHub OSPO for our own use and developed in a way that we could open source it that it might be useful to you as well! If you want to know more about how we use it, reach out in an issue in this repository.
@@ -40,7 +42,6 @@ Below are the allowed configuration options:
 | `START_DATE`                | False |   Beginning of time      | The date from which you want to start gathering contributor information. ie. Aug 1st, 2023 would be `2023-08-01` If `start_date` and `end_date` are specified then the action will determine if the contributor is new. A new contributor is one that has contributed in the date range specified but not before the start date. **Performance Note:** Using start and end dates will reduce speed of the action by approximately 63X. ie without dates if the action takes 1.7 seconds, it will take 1 minute and 47 seconds.|
 | `END_DATE`                | False |   Current Date      | The date at which you want to stop gathering contributor information. Must be later than the `START_DATE`. ie. Aug 2nd, 2023 would be `2023-08-02` If `start_date` and `end_date` are specified then the action will determine if the contributor is new. A new contributor is one that has contributed in the date range specified but not before the start date. |
 
-
 ### Example workflows
 
 TO BE WRITTEN
@@ -49,6 +50,13 @@ TO BE WRITTEN
 
 # Contributors
 
+Date range for contributor list:  2021-01-01 to 2023-10-10
+Organization: super-linter
+
+| Total Contributors | Total Contributions | % new contributors |
+| --- | --- | --- |
+| 1 | 143 | 0% |
+
 | Username | Contribution Count | New Contributor | Commits |
 | --- | --- | --- | --- |
 | zkoppert | 143 | False | https://github.com/super-linter/super-linter/commits?author=zkoppert&since=2021-01-01&until=2023-10-10 |
@@ -57,6 +65,12 @@ TO BE WRITTEN
 
 # Contributors
 
+Organization: super-linter
+
+| Total Contributors | Total Contributions |
+| --- | --- |
+| 1 | 210 |
+
 | Username | Contribution Count | Commits |
 | --- | --- | --- |
 | zkoppert | 210 | https://github.com/super-linter/super-linter/commits?author=zkoppert |

diff --git a/contributors.py b/contributors.py
@@ -42,7 +42,9 @@ def main():
 
     # Output the contributors information
     # print(contributors)
-    markdown.write_to_markdown(contributors, "contributors.md", start_date, end_date)
+    markdown.write_to_markdown(
+        contributors, "contributors.md", start_date, end_date, organization, repository
+    )
     # write_to_json(contributors)
 
 

diff --git a/markdown.py b/markdown.py
@@ -1,7 +1,10 @@
+# pylint: disable=too-many-locals
 """This module contains the functions needed to write the output to markdown files."""
 
 
-def write_to_markdown(collaborators, filename, start_date, end_date):
+def write_to_markdown(
+    collaborators, filename, start_date, end_date, organization, repository
+):
     """
     This function writes a list of collaborators to a markdown file in table format.
     Each collaborator is represented as a dictionary with keys 'username', 'contribution_count', 'new_contributor', and 'commits'.
@@ -10,16 +13,26 @@ def write_to_markdown(collaborators, filename, start_date, end_date):
         collaborators (list): A list of dictionaries, where each dictionary represents a collaborator.
                               Each dictionary should have the keys 'username', 'contribution_count', and 'commits'.
         filename (str): The path of the markdown file to which the table will be written.
+        start_date (str): The start date of the date range for the contributor list.
+        end_date (str): The end date of the date range for the contributor list.
+        organization (str): The organization for which the contributors are being listed.
+        repository (str): The repository for which the contributors are being listed.
+
+    Returns:
+        None
 
     """
+    # Put together the contributor table
     if start_date and end_date:
         headers = "| Username | Contribution Count | New Contributor | Commits |\n| --- | --- | --- | --- |\n"
     else:
         headers = "| Username | Contribution Count | Commits |\n| --- | --- | --- |\n"
 
     table = headers
+    total_contributions = 0
 
     for collaborator in collaborators:
+        total_contributions += collaborator.contribution_count
         username = collaborator.username
         contribution_count = collaborator.contribution_count
         commit_url = collaborator.commit_url
@@ -32,8 +45,44 @@ def write_to_markdown(collaborators, filename, start_date, end_date):
 
         table += row
 
+    # Put together the summary table including # of new contributions, # of new contributors, % new contributors, % returning contributors
+    if start_date and end_date:
+        summary_table = "| Total Contributors | Total Contributions | % new contributors |\n| --- | --- | --- |\n"
+        summary_table += (
+            "| "
+            + str(len(collaborators))
+            + " | "
+            + str(total_contributions)
+            + " | "
+            + str(
+                round(
+                    (len([x for x in collaborators if x.new_contributor is True]))
+                    / len(collaborators)
+                    * 100,
+                    2,
+                )
+            )
+            + "% | \n\n"
+        )
+    else:
+        summary_table = "| Total Contributors | Total Contributions |\n| --- | --- |\n"
+        summary_table += (
+            "| " + str(len(collaborators)) + " | " + str(total_contributions) + " |\n\n"
+        )
+
+    # Write the markdown file
     with open(filename, "w", encoding="utf-8") as markdown_file:
         markdown_file.write("# Contributors\n\n")
+        if start_date and end_date:
+            markdown_file.write(
+                f"Date range for contributor list:  {start_date} to {end_date}\n"
+            )
+        if organization:
+            markdown_file.write(f"Organization: {organization}\n")
+        if repository:
+            markdown_file.write(f"Repository: {repository}\n")
+        markdown_file.write("\n")
+        markdown_file.write(summary_table)
         markdown_file.write(table)
         markdown_file.write(
             "\n _this file was generated by the [Contributors GitHub Action](https://github.com/github/contributors)_\n"

diff --git a/test_markdown.py b/test_markdown.py
@@ -36,10 +36,18 @@ def test_write_to_markdown(self, mock_file):
             person2,
         ]
 
-        write_to_markdown(collaborators, "filename", "2023-01-01", "2023-01-02")
+        write_to_markdown(
+            collaborators, "filename", "2023-01-01", "2023-01-02", None, None
+        )
 
         mock_file.assert_called_once_with("filename", "w", encoding="utf-8")
         mock_file().write.assert_any_call("# Contributors\n\n")
+        mock_file().write.assert_any_call(
+            "Date range for contributor list:  2023-01-01 to 2023-01-02\n"
+        )
+        mock_file().write.assert_any_call(
+            "| Total Contributors | Total Contributions | % new contributors |\n| --- | --- | --- |\n| 2 | 300 | 50.0% | \n\n"
+        )
         mock_file().write.assert_any_call(
             "| Username | Contribution Count | New Contributor | Commits |\n"
             "| --- | --- | --- | --- |\n"