Add file modification history update script

[haszi]

Add file modification history update script. This script can be used to update the fileModHistory.php files in the documentation repos which contain the last modification date/time and the contributor list for every file in the repo.

The ideal way to use this script would be something like a pre-commit hook which would generate the update to the history file, and be merged and potentially reverted together with its parent commit. If anyone knows how to do this on GitHub, please let me know.

[Girgias]

@shivammathur would you possibly know how to do the git commit hooks?

[shivammathur]

@Girgias @haszi

To create a pre-commit hook, we have to create a executable .git/hooks/pre-commit file that runs scripts/updateModHistory.php.

But to enforce that this file is there on all clones, we have a couple of options.

If we can add composer to this project, we can run a post install script that copies the pre-commit file to git/hooks/pre-commit.

Another alternative is using https://pre-commit.com/

[haszi]

@shivammathur Thanks for the explanation.

Maybe a pre-commit hook wasn't a good idea for this problem after all. I think there is a way to achieve the same thing in the language repos by the workflow below. I do have some questions though:

Would this workflow trigger for every merge/revert on the repo?
Would the git commit --amend work without any issues?

on:
  push:
    branches:
      - master

jobs:
  if_merged:
    if: github.event.pull_request.merged == true
      runs-on: ubuntu-latest
      steps:
        - name: Checkout documentation
          uses: actions/checkout@v4

        - name: Update fileModHistory.php
          run: |
            # generate the updates to fileModHistory.php
            php updateModHistory.php

            # add and amend generated changes to the last commit
            git add fileModHistory.php            
            git commit --amend

[shivammathur]

@haszi

It will be better to run it on the pull_request closed event, and then check to make sure it was merged when it was closed.

https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#running-your-pull_request-workflow-when-a-pull-request-merges

I would suggest making a new commit and pushing it to master from CI instead of amending the PR commit. Also to push it to master it will need write permission on the GITHUB_TOKEN secret, so configure that using the permissions key.

on:
  pull_request:
    types:
      - closed
    branches:
      - master
permissions:
  contents: write
jobs:
  if_merged:
    if: github.event.pull_request.merged == true
      runs-on: ubuntu-latest
      steps:
        - name: Checkout documentation
          uses: actions/checkout@v4

        - name: Update fileModHistory.php
          env:
            GITHUB_TOKEN
          run: |
            # generate the updates to fileModHistory.php
            php updateModHistory.php
            
            # Configure git
            git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
            git config --local user.name "github-actions[bot]"

            # add and amend generated changes to the last commit
            git add fileModHistory.php            
            git commit -m "Update fileModHistory.php"
        - name: Push changes
          uses: ad-m/github-push-action@master
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            branch: master

[haszi]

I've discussed the adding of new commits instead of amending commits with Girgias and the fileModHistory.php file would probably have to be in a dedicated repo so as not to spam the documentation repos' commit history. In that scenario the workflow would still be triggered by the documentation repos after PRs are merged, which would have to pull their respective fileModHistory.php file from its repo, run the update script and commit the changes back to the file's repo.

I do have one question regarding the action/workflow: would this also run the update script when commits are reverted? It would be great if the reverts could use the same workflow even though there probably aren't too many PRs reverted in the doc-* repos.

[shivammathur]

@haszi Yes, the workflow with pull_request event would run on the revert PR as well.

[haszi]

@shivammathur I've tested the workflow and it works like a charm. I had to add

      with:
        fetch-depth: 0

under the "Checkout documentation" step to make my script work (it needs the entire git history) and the file modification info file is now being generated perfectly in the same repo.

Could you also point me in the right direction on how to check out the fileModHistory.php file from another repo, run the script to make updates and push the file back to the repo it was checked out of?

[haszi]

@Girgias I opened this PR up for review as the script itself is ready. The changes in the last commit make the script accept both the path of the documentation and that of the "history file" as command line parameters, so this can be called (directly or from a GitHub workflow) from within the same or another repo.

[Girgias]

I haven't tried it locally yet, but some minor nits.

Also @cmb69 @jimwins may want to have a look

[Girgias]

Maybe have a variable for the space indent?

[haszi]

I used strlen() in my last commit. Will that work too or would a variable be better in this case?

[cmb69]

Sorry, I do not understand the purpose of having a fileModHistory.php file.

[haszi]

Sorry, I do not understand the purpose of having a fileModHistory.php file.

My bad!

The idea behind this file and the script is that every time a PR is merged into any of the documentations, the script generates a file (fileModHistory.php) with a PHP associative array. This array contains the hash of the last merged commit and a the list of all files in that doc repo. For each file, the last date/time that file was updated and list of all commit authors is recorded as well. This information then would be shown on each of the documentation pages (see this PR for screenshots) and could be used to generate a list of all authors that could be added to the list of authors/editors on the Preface page.

The script in this PR is for generating the file (fileModHistory.php) with the all the above information and it should work from either the command line or from a GitHub workflow. The script would be used like this:

php updateModHistory.php --docs-path=/path/doc/doc-repo --history-path=/path/to/existing/fileModHistoryFile.php

[cmb69]

Thanks @haszi for the explanation! While this is low priority for me, I understand that it will be more important for others, so I'm generally fine with the approach.

[Girgias]

Use sprintf or var_export here?

[haszi]

Something like this?

$newModHistoryString = sprintf("%4s\"%s\" => [\n%8s\"modified\" => \"%s\",\n%8s\"contributors\" => [\n", 
    " ", 
    $fileName, 
    " ", 
    $fileProps["modified"] ?? "",
    " "
);

[Girgias]

Possibly, but this really minor actually.

[Girgias]

Ditto

[haszi]

Will this work?

$newModHistoryString .= sprintf("%8s],\n%4s],\n", " ", " ");

[cmb69]

I guess this is good; can't test anyway, since I cannot afford a bash. :)