RtD docs previews: Cancel building PRs if no changes in Doc dir

[hugovk]

As suggested by @humitos at #103843 (comment), cancel building pull requests when there aren't changes in the Doc directory.

If there are no changes (git diff exits with 0) we force the command to return with 183. This is a special exit code on Read the Docs that will cancel the build immediately.

https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition

[hugovk]

For the first commit:

Problem in your project's configuration. Invalid "build.commands": .readthedocs.yml: The keys build.jobs and build.commands can't be used together.

https://readthedocs.org/projects/cpython-previews/builds/20362322/

For the second:

We encountered a problem with a command while building your project. To resolve this error, double check your project configuration and installed dependencies are correct and have not changed recently.
...
/bin/sh: 1: if: not found
/bin/sh: 2: Syntax error: "then" unexpected

https://readthedocs.org/projects/cpython-previews/builds/20362458/

@humitos Any suggestions? Thank you!

[Eclips4]

Just guessing, maybe move all commands and lines of bash code into jobs/post_checkout section will help?

[sobolevn]

Hm, looks like sh cannot handle ] && expr case. Better use [ ] twice.

[sobolevn]

Sorry, I should have posted the full version right away :)

[humitos]

Hi! Sorry for the late reply. I've been on vacations and then Write the Docs conference after that.

I was 100% sure that we already solved the problem you are facing, but I just found that we reverted the change because it was causing other issues (readthedocs/readthedocs.org#10206). I'm sorry for the confusion here.

As @Eclips4 commented, putting this into a script and calling it from build.jobs.post_ should work as a workaround.

[humitos]

Interesting... It seems it works fine with build.jobs (I tested it again at https://readthedocs.org/projects/test-builds/builds/20716439/) but it doesn't with build.commands for some reason. I will need to keep researching about this and I will come back, hopefully, with a solution 😄

[sobolevn]

It works locally, maybe this is some kind of yaml issue?

sh-3.2$ if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && [ "$(git diff --quiet origin/main -- Doc/ .readthedocs.yml; echo $?)" -eq 0 ]; then
>   echo 1
> fi
sh-3.2$ 

[sobolevn]

Maybe like this?

- if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && [ "$(git diff --quiet origin/main -- Doc/ .readthedocs.yml; echo $?)" -eq 0 ]; then \
    echo "No changes to Doc/ - exiting the build."; \
    exit 183; \
  fi

[sobolevn]

I have no idea what is going on :)
Maybe we are missing something obvious?

[humitos]

Today we are deploying a change on Read the Docs that should fix this. Hopefully, it works 🤞🏼

[humitos]

The fix on Read the Docs is already deployed and my tests worked. Can you confirm that it works for you now as well? Note that you have to adapt your command to revert it to the state it was before (multi-line). I will do a suggestion on the PR.

[hugovk]

This is working quite well, thanks!

One thing though, for example on #105008 (comment), the build was cancelled as expected:

Details

https://readthedocs.org/projects/cpython-previews/builds/20835824/

However, the status check on GitHub still shows as pending:

Details

And also shows in the tab:

Details

Would it be possible to have it report as skipped instead of pending?

[humitos]

Hi @hugovk. This should be reporting success (✅) to GitHub when the build is skipped. It seems we introduced a bug here or something that broke this behavior. If you have the time, please open an issue in https://github.com/readthedocs/readthedocs.org/

[hugovk]

Thanks, reported: readthedocs/readthedocs.org#10364

---

Another PR had no Doc/ or .readthedocs.yml changes but still built the docs preview:

• gh-89886: Rely on HAVE_SYS_TIME_H #105058
• de000c6
• https://readthedocs.org/projects/cpython-previews/builds/20850890/
• https://cpython-previews--105058.org.readthedocs.build/en/105058/

We can see the check was there but returned 0:

if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && [ "$(git diff --quiet origin/main -- Doc/ .readthedocs.yml; echo $?)" -eq 0 ];
then
  echo "No changes to Doc/ - exiting the build.";
  exit 183;
fi

Any ideas why this didn't skip?