Merge pull request #18 from per1234/size-reports

Add ability for libraries actions to report changes in memory usage

Author: Roberto Sora

libraries/compile-examples/Dockerfile

@@ -1,12 +1,15 @@
-# Container image that runs your code
-FROM ubuntu:latest
+FROM python:3.8.2
 
 # Install prerequisites
-RUN apt-get update --quiet=2 && apt-get install --quiet=2 --assume-yes wget
-CMD /bin/bash
+RUN apt-get update && apt-get install -y git wget jq curl \
+    && rm -rf /var/lib/apt/lists/*
 
 # Copies your code file from your action repository to the filesystem path `/` of the container
 COPY entrypoint.sh /entrypoint.sh
+COPY reportsizetrends /reportsizetrends
+
+# Install python dependencies
+RUN pip install -r /reportsizetrends/requirements.txt
 
 # Code file to execute when the docker container starts up (`entrypoint.sh`)
 ENTRYPOINT ["/entrypoint.sh"]

libraries/compile-examples/README.md

@@ -20,10 +20,105 @@ For 3rd party boards, also specify the Boards Manager URL:
 
 List of library dependencies to install (space separated). Default `""`.
 
+### `github-token`
+
+GitHub access token used to get information from the GitHub API. Only needed if you're using the size report features with private repositories. It will be convenient to use [`${{ secrets.GITHUB_TOKEN }}`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token). Default `""`.
+
+### `size-report-sketch`
+
+Name of the sketch used to compare memory usage change. Default `""`.
+
+### `enable-size-deltas-report`
+
+Set to `true` to cause the action to determine the change in memory usage for the [`size-reports-sketch`](#size-reports-sketch) between the pull request branch and the tip of the pull request's base branch. This may be used with the [`arduino/actions/libraries/report-size-deltas` action](https://github.com/arduino/actions/tree/master/libraries/report-size-deltas). Default `false`.
+
+### `size-deltas-report-folder-name`
+
+Folder to save the JSON formatted memory usage change reports to. Should be used only to store reports. It will be created under [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. Default `"size-deltas-reports"`.
+
+### `enable-size-trends-report`
+
+Set to `true` to cause the action to record the memory usage of [`size-reports-sketch`](#size-reports-sketch) to a Google Sheets spreadsheet on every push to the repository's default branch. Default `false`.
+
+### `keyfile`
+
+Contents of the Google key file used to update the size trends report Google Sheets spreadsheet. This should be defined using a [GitHub secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). Default `""`.
+1. Open https://console.developers.google.com/project
+1. Click the "Create Project" button.
+1. In the "Project name" field, enter the name you want for your project.
+1. You don't need to select anything from the "Location" menu.
+1. Click the button with the three horizontal lines at the top left corner of the window.
+1. Hover the mouse pointer over "APIs & Services".
+1. Click "Library".
+1. Make sure the name of the project you created is selected from the dropdown menu at the top of the window.
+1. Click 'Google Sheets API".
+1. Click the "Enable" button.
+1. Click the "Create Credentials" button.
+1. From the "Which API are you using?" menu, select "Google Sheets API".
+1. From the "Where will you be calling the API from?" menu, select "Other non-UI".
+1. From the "What data will you be accessing?" options, select "Application data".
+1. From the "Are you planning to use this API with App Engine or Compute Engine?" options, select "No, I’m not using them".
+1. Click the "What credentials do I need?" button.
+1. In the "Service account name" field, enter the name you want to use for the service account.
+1. From the "Role" menu, select "Project > Editor".
+1. From the "Key type" options, select "JSON".
+1. Click the "Continue" button. The .json file containing your private key will be downloaded. Save this somewhere safe.
+1. Open the downloaded file.
+1. Copy the entire contents of the file to the clipboard.
+1. Open the GitHub page of the repository you are configuring the GitHub Actions workflow for.
+1. Click the "Settings" tab.
+1. From the menu on the left side of the window, click "Secrets".
+1. Click the "Add a new secret" link.
+1. In the "Name" field, enter the variable name you want to use for your secret. This will be used for the `size-trends-report-key-file` argument of the `compile-examples` action in your workflow configuration file. For example, if you named the secret `GOOGLE_KEY_FILE`, you would reference it in your workflow configuration as `${{ secrets.GOOGLE_KEY_FILE }}`.
+1. In the "Value" field, paste the contents of the key file.
+1. Click the "Add secret" button.
+1. Open the downloaded key file again.
+1. Copy the email address shown in the `client_email` field.
+1. Open Google Sheets: https://docs.google.com/spreadsheets
+1. Under "Start a new spreadsheet", click "Blank".
+1. Click the "Share" button at the top right corner of the window.
+1. If you haven't already, give your spreadsheet a name.
+1. Paste the `client_email` email address into the "Enter names or email addresses..." field.
+1. Uncheck the box next to "Notify people".
+1. Click the "OK" button.
+1. In the "Skip sending invitations?" dialog, click the "OK" button.
+
+### `size-trends-report-spreadsheet-id`
+
+The ID of the Google Sheets spreadsheet to write the memory usage trends data to. The URL of your spreadsheet will look something like `https://docs.google.com/spreadsheets/d/15WOp3vp-6AnTnWlNWaNWNl61Fe_j8UJhIKE0rVdV-7U/edit#gid=0`. In this example, the spreadsheet ID is `15WOp3vp-6AnTnWlNWaNWNl61Fe_j8UJhIKE0rVdV-7U`. Default `""`.
+
+### `size-trends-report-sheet-name`
+
+The sheet name in the Google Sheets spreadsheet used for the memory usage trends report. Default `"Sheet1"`.
+
 ## Example usage
 
+Only compiling examples:
+```yaml
+- uses: arduino/actions/libraries/compile-examples@master
+  with:
+    fqbn: 'arduino:avr:uno'
+```
+
+Storing the memory usage change report as a [workflow artifact](https://help.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts):
+```yaml
+- uses: arduino/actions/libraries/compile-examples@master
+  with:
+    size-report-sketch: Foobar
+    enable-size-deltas-report: true
+- if: github.event_name == 'pull_request'
+  uses: actions/upload-artifact@v1
+  with:
+    name: size-deltas-reports
+    path: size-delta-reports
+```
+
+Publishing memory usage trends data to a Google Sheets spreadsheet:
 ```yaml
-uses: arduino/actions/libraries/compile-examples@master
-with:
-  fqbn: 'arduino:avr:uno'
+- uses: arduino/actions/libraries/compile-examples@master
+  with:
+    size-report-sketch: Foobar
+    enable-size-trends-report: true
+    keyfile: ${{ secrets.GOOGLE_KEY_FILE }}
+    size-trends-report-spreadsheet-id: 15WOp3vp-6AnTnWlNWaNWNl61Fe_j8UJhIKE0rVdV-7U
 ```

libraries/compile-examples/action.yml

@@ -10,10 +10,41 @@ inputs:
   libraries:
     description: 'List of library dependencies to install (space separated)'
     default: ''
+  github-token:
+    description: 'GitHub access token used to get information from the GitHub API. Only needed if you are using the size report features with private repositories.'
+    default: ''
+  size-report-sketch:
+    description: 'Name of the sketch used to compare memory usage change'
+    default: ''
+  enable-size-deltas-report:
+    description: 'Set to true to cause the action to determine the change in memory usage for the size-reports-sketch'
+    default: false
+  size-deltas-report-folder-name:
+    description: 'Folder to save the memory usage change report to'
+    default: 'size-deltas-reports'
+  enable-size-trends-report:
+    description: 'Set to true to cause the action to record the memory usage of size-reports-sketch'
+    default: false
+  keyfile:
+    description: 'Google key file used to update the size trends report Google Sheets spreadsheet.'
+    default: ''
+  size-trends-report-spreadsheet-id:
+    description: 'The ID of the Google Sheets spreadsheet to write the memory usage trends data to'
+    default: ''
+  size-trends-report-sheet-name:
+    description: 'The sheet name in the Google Sheets spreadsheet used for the memory usage trends report'
+    default: 'Sheet1'
 runs:
   using: 'docker'
   image: 'Dockerfile'
   args:
     - ${{ inputs.cli-version }}
     - ${{ inputs.fqbn }}
     - ${{ inputs.libraries }}
+    - ${{ inputs.github-token }}
+    - ${{ inputs.size-report-sketch }}
+    - ${{ inputs.enable-size-deltas-report }}
+    - ${{ inputs.size-deltas-report-folder-name }}
+    - ${{ inputs.enable-size-trends-report }}
+    - ${{ inputs.size-trends-report-spreadsheet-id }}
+    - ${{ inputs.size-trends-report-sheet-name }}