Document shallow clone depth's effect on changesets

[TobiLabu]

I stumbled across an issue concerning the files shown in changesets. Since some date the changesets would list all files of the repository instead of only the changed ones. I tried looking for a recent change within the Jenkins codebase that might cause this issue and came across this comment. I realized I had made the same configuration change to reduce load.
This PR adds a note in the help text of the configuration parameter (I first started to write an issue, but since this is only a small change in the documentation, I followed the hint to just create a PR instead).

Testing done

I did not build the plugin to test this. As it is a minor documentation change, I am quite confident it works as expected. I am, however, not a native English speaker, so if the wording seems off, feel free to let me know.

Submitter checklist

• Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
• Ensure that the pull request title represents the desired changelog entry
• Please describe what you did
• Link to relevant issues in GitHub or Jira
• Link to relevant pull requests, esp. upstream and downstream changes
• Ensure you have provided tests that demonstrate the feature works or the issue is fixed

[MarkEWaite]

Thanks for documenting the behavior. I've confirmed the same behavior.

I created a Pipeline job that shows the issue on the first build:

pipeline {
    agent {
        label 'alpine'
    }
    stages {
        stage('Shallow Clone') {
            steps {
                checkout scmGit(branches: [[name: 'JENKINS-76158']],
                                extensions: [cloneOption(honorRefspec: true, noTags: true, shallow: true, depth: 1),
                                             firstBuildChangelog(),
                                             localBranch()],
                                userRemoteConfigs: [[name: 'origin',
                                                     refspec: '+refs/heads/JENKINS-76158:refs/remotes/origin/JENKINS-76158',
                                                     url: 'https://github.com/MarkEWaite/jenkins-bugs']])
            }
        }
    }
}

The firstBuildChangelog extension should show the changes in the most recent commit. The only file changed in the most recent commit is build.number, but instead it shows all files as changed.

I think this is a bug, but it is probably better to document the bug immediately and then fix the bug in a future release.

Can you offer your opinion on what should be displayed as the changes for a repository that has been shallow cloned? Some scenarios to consider:

• Depth 1 (the most common case). Should the changes only include the files listed in git log --numstat for the most recent commit?
  • Fresh workspace (ephemeral agent) - only include the files listed in git log --numstat for the most recent commit
  • Existing workspace (permanent agent) - include files listed in git log --numstat for the most recent commit and for any intervening commits that were not included in the previous build. That will skip commits that happened between the most recent commit and the commit that was used in the previous build
• Depth more than 1 (uncommon, but valid). Should the changes include files listed in git log --numstat for the most recent commit and for any intervening commits that were not included in the previous build?

[MarkEWaite]

If the shallow clone depth is set to 2, then the changes list seems to only list the changes in the most recent commit. That might be a workaround until a fix is available.

[TobiLabu]

I am not sure if I'd consider it a bug. Looking at Git's behaviour concerning clone --depth x it seems obvious that the changes cannot be displayed correctly when I "squash" all the commit history that is used to detect these changes.

At least for my use case I think a better solution would be an option that uses git clone --shallow-since <lastBuildTime>. This would include all the commits needed to decide if certain steps of the pipeline can be omitted. I don't know if this is feasible for the plugin.