Further improvements to how pull request documentation gets cleaned up.

[moe-ad]

I think this is best explained with an example.

Suppose PR-1 and PR-2 both have deployed documentation in some repo (usually an high activity repo or one where doc generation takes a long time). Consider four points in time: u < x < y < z.

• At time u, PR-1 triggers the doc-deploy-pr workflow. At this moment, the deployment contains documentation for both PR-1 and PR-2 (i.e. pull/1 and pull/2 directories exist on the gh-pages branch).
• At time x, PR-2 is merged, which triggers the doc-deploy-dev workflow.
• That workflow finishes at time y, removing the deployed documentation for PR-2 (the pull/2 directory is removed).
• Later, at time z, the workflow that started at time u finishes.

The problem is that the workflow started at u still “thinks” PR-2 exists, because it captured the state before PR-2 was merged (i.e. had information about pull/2). When it finishes at z, it redeploys documentation for PR-2, effectively undoing the removal that happened at time y.

Is there a way we can avoid this?

This is leading to problems like this or this (repeated removal since subsequent runs of doc-deploy-dev will still remove documentation for a closed pull request even if it made its way back into deployment via the situation described above).

[RobPasMue]

You could switch the doc-deploy-pr action to only publish the pull request directory and whatever other extra files get touched. That way if a change has occurred regarding cleanup, you shouldn't be impacted. The main issue right now is that you are committing the entire gh-pages branch diffs.

With this approach I believe that it won't consider other directories that might or might not be there. It will only take into account your pull/n directory

[RobPasMue]

See

actions/_pr-doc-deployment/action.yml

Lines 336 to 342 in 4031f8e

	publish_dir: .
	publish_branch: ${{ inputs.branch }}
	personal_token: ${{ inputs.token }}
	external_repository: ${{ inputs.repository }}
	commit_message: ${{ inputs.commit-message }}
	keep_files: true
	force_orphan: ${{ inputs.force-orphan }}

Specifically the publish_dir could be modified. Or even the destination_dir. Perform an evaluation of the required changes based on their allowed inputs in here, but I believe these 2 might be your salvation

[jorgepiloto]

You are right, @RobPasMue. @moe-ad and I discussed about the force-orphan option. This introduces the following errors:

• Excessive build size and times since it pushes the whole content of the branch in a single commit
• Can cause conflicts like the one we are experiencing

The gh-pages branch must be an orphan branch but it does not necessarily need to have a single commit. We must fix this in our actions.

Let's address this for v12.3.0.

[RobPasMue]

We could keep the force-orphan option when:

• Fully deploying a release documentation

But maybe for the rest of the cases (to ease things) it might be best to just commit the diff.

I wouldn't completely remove the force-orphan option from our actions since gh-pages branch history might become super heavy... We need to have some "clean up" built-in mechanism. Assuming this cleanup happens whenever we do a release might be a good trade off. But I am up for a debate on this! =)

[moe-ad]

Thanks for the valuable inputs @RobPasMue, much appreciated.

Another potential issue with committing a diff (still assuming the PR-1/PR-2 scenario above) is that since the latest commit changes when PR-2 gets merged, git will complain by the time the PR-1 workflow tries to push it's own changes.

But I guess peaceiris/actions-gh-pages might be robust enough to automatically handle such situations (infact, let me be a dreamer and believe that for my sake and sanity).