This ensures that if a piece of feedback moves around within a given file (e.g. because lines were added or removed above this feedback) that we won't erroneously post the same comment again.
This job is our first official linter.
<img width="830" alt="screen shot 2018-08-30 at 5 12 35 pm" src="https://user-images.githubusercontent.com/45670/44880230-d8049780-ac79-11e8-926b-836b16c86f9f.png">
See https://github.com/material-components/material-components-ios/pull/4954 for an example thread in which I purposefully made some style regressions and let the tool post back to the PR until I resolved them.
This new job will apply clang-format *only* to the lines that have been changed by a given pull request. If any changes are suggested, the diff will be shown in the job's build logs and individual changes will be posted back to the PR at each suggested line.
The provided feedback can be addressed in multiple ways:
1. Manually, by copying the suggested changes into your code.
2. By running git-clang-format on your local branch. The tool will suggest this, including an ideal command line invocation to do so.
This job can be run locally, though it requires a fair amount of configuration to do so. See the job's documentation for more details on which environment variables are required.
---
This change also required modifications to the github-comment command line tool. Notably:
1. A very light-weight diff parser was added. This API takes a git diff [unified diff](https://www.gnu.org/software/diffutils/manual/html_node/Example-Unified.html#Example-Unified) file and parses it into individual [hunks](https://www.gnu.org/software/diffutils/manual/html_node/Hunks.html).
2. A hunk-correlator was added. This is the magic that translates clang-format's suggested diff into individual positions on a GitHub pull request.
3. A new GitHub API method for fetching a single file was added. We require this in order to fetch the pull request diff.
4. A new set of command line parameters was added to the github-comment tool. Use of these new parameters turn a suggested diff into a series of GitHub pull request line comments.
Before posting any new comments to the PR, the command enumerates all of the existing comments into a Set. If desired comment already exists in the set of comments then it will not be posted again. This is the mechanism by which we minimize noise generated from the job on subsequent updates to the PR.
---
The essential workflow for this tool is (on kokoro):
1. Install the clang-format version we're using internally by fetching it from our pre-built binary repository: https://github.com/material-foundation/clang-format
2. Install the git-clang-format tool.
3. Verify the checksums of both tools.
4. Run git-clang-format on the pull request.
5. If there have been no changes, exit with status 0 and post success back to the PR. Deletes any comment that had been made previously about style (this matches the apidiff behavior).
6. Otherwise, output the diff results and feed the diff to github-comment.
7. github-comment parses the pull request diff and the suggested diff, correlates the suggested hunks with the pull request hunks, and then posts individual line comments with the suggested changes.
8. If a summary comment hasn't already been posted to the PR, a summary comment is posted. Otherwise, we update the existing comment.
9. Post a failure status to the PR.
This resolves a warning that was appearing when building/running the github-comment project:
```
warning: Ignoring duplicate product 'github-comment'
```
Tested by running:
```
cd scripts/github-comment/
swift run github-comment
```
And verifying that the above warning did not appear and that the command successfully built and executed.
This command will generate an API diff for the current pull request. In a follow-up PR it will also post the results of the API diff to the PR as a comment.
This is the first of two changes to the `apidiff` branch that will add support for API diff reporting to our PRs. The second PR will add the github comment reporting tool.
This was previously reviewed in https://github.com/material-components/material-components-ios/pull/4181.
