testing_pull_requests.rst 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  1. .. _doc_testing_pull_requests:
  2. Testing pull requests
  3. =====================
  4. Many people are developing new features or fixing bugs on GitHub.
  5. To help with engine development, you may be asked to test those pull requests
  6. with a Godot build that includes code from the pull request in question.
  7. Thanks to GitHub Actions, all `pull requests <https://github.com/godotengine/godot/pulls>`__
  8. have continuous builds available. These builds let you try out pull requests
  9. without having to compile anything from source.
  10. Downloading a compiled build
  11. ----------------------------
  12. You can download pull request builds from GitHub Actions. Since only signed in
  13. users may download builds directly from GitHub Actions, the procedure varies
  14. depending on whether you have a GitHub account or not.
  15. .. note::
  16. Due to a GitHub Actions limitation, builds are only available for 90 days
  17. after the pull request was last updated. If you still wish to try a
  18. pull request locally, you can
  19. :ref:`compile the pull request branch from source <doc_testing_pull_requests_compile>`
  20. instead.
  21. If you have a GitHub account
  22. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  23. - Open the pull request page. Click the **Checks** tab near the top of the page:
  24. .. image:: img/testing_pull_requests_access_checks.png
  25. - In the list of platforms that appears on the left, select your platform by clicking
  26. it then choose the type of build you need (editor or export template).
  27. If in doubt, select an editor build:
  28. .. image:: img/testing_pull_requests_checks_platforms.png
  29. - Click the **Artifacts** dropdown on the right of the page then click the artifact's
  30. name to download it:
  31. .. image:: img/testing_pull_requests_checks_artifacts.png
  32. - Extract the ZIP archive then run the executable.
  33. Note that Windows and macOS binaries are not code signed.
  34. This means you may have to bypass a security warning before you can run the executable.
  35. If you frequently test pull request builds, it may be better to disable
  36. Windows SmartScreen or `disable macOS Gatekeeper <https://disable-gatekeeper.github.io/>`__ permanently.
  37. If you don't have a GitHub account
  38. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  39. If you don't have a GitHub account and can't sign up for one,
  40. you can use the third-party `nightly.link <https://nightly.link>`__ service
  41. to generate a universal download link.
  42. - Open the pull request page. Click the *fork*'s branch name near the top of the page:
  43. .. image:: img/testing_pull_requests_access_fork.png
  44. - Now that you are on the fork's branch page, click the ``.github`` folder at the top of the file list.
  45. Then, click on the ``workflows`` folder (whicb is inside the ``.github`` folder).
  46. Click the workflow file for the platform you wish to download artifacts for.
  47. *After* clicking on the file (which opens the file view), copy the page URL from your browser's address bar.
  48. - Open the `nightly.link <https://nightly.link>`__ website and paste the URL you just copied
  49. into the text field located below the heading **Paste a GitHub link, get a nightly.link!**.
  50. After pasting the URL, click **Get links** on the right.
  51. If the the format of the URL you pasted is correct, you should be presented
  52. with a page like this:
  53. .. image:: img/testing_pull_requests_nightly_link.png
  54. - Click the URL of the artifact you wish to download.
  55. - Extract the ZIP archive then run the executable.
  56. Note that Windows and macOS binaries are not code signed.
  57. This means you may have to bypass a security warning before you can run the executable.
  58. If you frequently test pull request builds, it may be better to disable
  59. Windows SmartScreen or `disable macOS Gatekeeper <https://disable-gatekeeper.github.io/>`__ permanently.
  60. .. _doc_testing_pull_requests_compile:
  61. Compiling a pull request branch from source
  62. -------------------------------------------
  63. This approach may be needed for pull requests that were last updated more than
  64. 90 days ago, or to test on platforms and configurations that are not supported
  65. by Godot's GitHub Actions setup.
  66. - Open the pull request page. Click the *fork*'s branch name near the top of the page:
  67. .. image:: img/testing_pull_requests_access_fork.png
  68. - Now that you are on the fork's branch page, click the green **Code** button on the right of the page
  69. then choose **Download ZIP** in the dropdown:
  70. .. image:: img/testing_pull_requests_fork_zip.png
  71. - Extract the ZIP archive and follow the :ref:`compiling <toc-devel-compiling>` instructions
  72. for your operating system.