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?