diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_android.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_android.md index 5df0f9e..43757cc 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_android.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_android.md @@ -1,8 +1,6 @@ # Compiling for Android -.. highlight:: shell - :::info This page describes how to compile Android export template binaries from source. diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_ios.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_ios.md index fed36cf..d9fca16 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_ios.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_ios.md @@ -1,8 +1,6 @@ # Compiling for iOS -.. highlight:: shell - :::info This page describes how to compile iOS export template binaries from source. diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_linuxbsd.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_linuxbsd.md index e3c4d31..c430b60 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_linuxbsd.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_linuxbsd.md @@ -1,7 +1,5 @@ # Compiling for Linux, \*BSD -.. highlight:: shell - :::info This page describes how to compile Linux editor and export template binaries from source. diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_macos.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_macos.md index 548de08..666c325 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_macos.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_macos.md @@ -1,8 +1,6 @@ # Compiling for macOS -.. highlight:: shell - :::note This page describes how to compile macOS editor and export template binaries from source. diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_web.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_web.md index dbf0706..d0e8f58 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_web.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_web.md @@ -8,8 +8,6 @@ If you're looking to export your project to HTML5 instead, read [doc_exporting_f ::: -.. highlight:: shell - ## Requirements To compile export templates for the Web, the following is required: diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_windows.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_windows.md index d5d1739..5843c5c 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_windows.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_for_windows.md @@ -1,8 +1,6 @@ # Compiling for Windows -.. highlight:: shell - :::info This page describes how to compile Windows editor and export template binaries from source. diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_dotnet.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_dotnet.md index 04ebb9d..fc0f9f4 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_dotnet.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_dotnet.md @@ -1,8 +1,6 @@ # Compiling with .NET -.. highlight:: shell - ## Requirements - [.NET SDK 8.0+](https://dotnet.microsoft.com/download) diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_script_encryption_key.md b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_script_encryption_key.md index 30e95d9..ffeb18f 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_script_encryption_key.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/compiling_with_script_encryption_key.md @@ -1,7 +1,5 @@ # Compiling with PCK encryption key -.. highlight:: shell - The export dialog gives you the option to encrypt your PCK file with a 256-bit AES key when releasing your project. This will make sure your scenes, scripts and other resources are not stored in plain text and can not easily be ripped diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/cross-compiling_for_ios_on_linux.md b/Redot-Documentation/docs/Contributing/Development/compiling/cross-compiling_for_ios_on_linux.md index 0a833cd..82e518a 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/cross-compiling_for_ios_on_linux.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/cross-compiling_for_ios_on_linux.md @@ -1,8 +1,6 @@ # Cross-compiling for iOS on Linux -.. highlight:: shell - The procedure for this is somewhat complex and requires a lot of steps, but once you have the environment properly configured you can compile Redot for iOS anytime you want. diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/getting_source.md b/Redot-Documentation/docs/Contributing/Development/compiling/getting_source.md index c273d6e..15de59c 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/getting_source.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/getting_source.md @@ -1,8 +1,6 @@ # Getting the source -.. highlight:: shell - ## Downloading the Redot source code Before [getting into the SCons build system](introduction_to_the_buildsystem.md) diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/introduction_to_the_buildsystem.md b/Redot-Documentation/docs/Contributing/Development/compiling/introduction_to_the_buildsystem.md index 0d6492b..82fc382 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/introduction_to_the_buildsystem.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/introduction_to_the_buildsystem.md @@ -1,7 +1,5 @@ # Introduction to the buildsystem -.. highlight:: shell - Redot is a primarily C++ project and it [uses the SCons build system.](doc_faq_why_scons) We love SCons for how maintainable and easy to set up it makes our buildsystem. And thanks to that compiling Redot from source can be as simple as running diff --git a/Redot-Documentation/docs/Contributing/Development/compiling/optimizing_for_size.md b/Redot-Documentation/docs/Contributing/Development/compiling/optimizing_for_size.md index 3f40f96..5bbe37a 100644 --- a/Redot-Documentation/docs/Contributing/Development/compiling/optimizing_for_size.md +++ b/Redot-Documentation/docs/Contributing/Development/compiling/optimizing_for_size.md @@ -1,8 +1,6 @@ # Optimizing a build for size -.. highlight:: shell - ## Rationale Sometimes, it is desired to optimize a build for size rather than speed. diff --git a/Redot-Documentation/docs/Contributing/Workflow/bisecting_regressions.md b/Redot-Documentation/docs/Contributing/Workflow/bisecting_regressions.md index c40d07e..0c196e5 100644 --- a/Redot-Documentation/docs/Contributing/Workflow/bisecting_regressions.md +++ b/Redot-Documentation/docs/Contributing/Workflow/bisecting_regressions.md @@ -1,8 +1,6 @@ # Bisecting regressions -.. highlight:: shell - Bisecting is a way to find regressions in software. After reporting a bug on the [Redot repository on GitHub](https://github.com/redot-engine/redot), you may be asked by a contributor to *bisect* the issue. Bisecting makes it possible for @@ -26,16 +24,16 @@ Before using Git's ``bisect`` command, we strongly recommend trying to reproduce the bug with an older (or newer) official release. This greatly reduces the range of commits that potentially need to be built from source and tested. You can find binaries of official releases, as well as alphas, betas, -and release candidates [here](https://downloads.tuxfamily.org/Redotengine/). +and release candidates [here](https://github.com/Redot-Engine/redot-engine/releases). -If you have experience with Redot 3.x and can reproduce an issue with Redot 4.0, -we recommend trying to reproduce the issue in the latest Redot 3.x version (if -the feature exhibiting the bug is present in 3.x). This can be used to check -whether the issue is a regression in 4.0 or not. +If you have experience with Godot 4.x and can reproduce an issue with Redot 26.2, +we recommend trying to reproduce the issue in the latest Godot 4.x version (if +the feature exhibiting the bug is present in 4.x). This can be used to check +whether the issue is a regression in 26.2 or not. -- If the issue **is present** in 3.x, then you'll need to check whether the issue - occurs in older 3.x versions as well. -- If the issue is **not present** in 3.x, then you can try older 4.0 alphas and +- If the issue **is present** in 26.x, then you'll need to check whether the issue + occurs in older 26.x versions as well. +- If the issue is **not present** in 26.x, then you can try older 26.2 alphas and betas to determine when the regression started. :::danger @@ -64,7 +62,7 @@ reproduce the bug. Before bisecting a regression, you need to set up a build environment to compile Redot from source. To do so, read the -[Compiling](toc-devel-compiling) page for your target platform. +[Compiling](doc_introduction_to_the_buildsystem) page for your target platform. (Compiling Redot from source doesn't require C++ programming knowledge.) Note that compiling Redot can take a while on slow hardware (up an hour for @@ -80,14 +78,16 @@ another contributor can continue bisecting from there. To start bisecting, you must first determine the commit hashes (identifiers) of the "bad" and "good" build. "bad" refers to the build that exhibits the bug, whereas "good" refers to the version that doesn't exhibit the bug. If you're -using a pre-release build as the "good" or "bad" build, browse the `download -mirror <https://downloads.tuxfamily.org/Redotengine/>`__, go to the folder that -contains the pre-release you downloaded and look for the ``README.txt`` file. -The commit hash is written inside that file. +using a pre-release build as the "good" or "bad" build, browse the +[download mirror](https://github.com/Redot-Engine/redot-engine/releases), go to +the folder that contains the pre-release you downloaded and look for the +``README.txt`` file. The commit hash is written inside that file. If you're using a stable release as the "good" or "bad" build, use one of the following commit hashes depending on the version: + + ```none 4.1.1-stable 4.1-stable @@ -118,9 +118,10 @@ following commit hashes depending on the version: You can also use this Bash function to retrieve the Git commit hash of a pre-release build (add it to your ``$HOME/.bashrc`` or similar): -``` -gd_snapshot_commit() { - curl -s https://downloads.tuxfamily.org/Redotengine/$1/$2/README.txt \ + +```shell +rd_snapshot_commit() { + curl -s https://downloads.tuxfamily.org/redot-engine/$1/$2/README.txt \ | grep 'from commit' \ | sed 's/^Built from commit \(.*\)\.$/\1/' } @@ -130,7 +131,7 @@ gd_snapshot_commit() { Example usage: ```shell -gd_snapshot_commit 4.0 beta4 +rd_snapshot_commit 4.0 beta4 ``` @@ -140,7 +141,7 @@ hashes, ``master`` is a perpetually moving target. ### Build the engine -[Get Redot's source code using Git](../Development/compiling/getting_source.md). Once this +[Get Redot's source code using Git](doc_getting_source). Once this is done, in the terminal window, use ``cd`` to reach the Redot repository folder and enter the following command: @@ -166,7 +167,7 @@ Run the binary located in the ``bin/`` folder and try to reproduce the bug. :::note -[Double-check the output file name](doc_introduction_to_the_buildsystem_resulting_binary) +[Double-check the output file name](doc_introduction_to_the_buildsystem#resulting_binary) in ``bin/`` to make sure you're actually running the binary you've just compiled. Different Redot versions will output binaries with different names. diff --git a/Redot-Documentation/docs/Contributing/Workflow/bug_triage_guidelines.md b/Redot-Documentation/docs/Contributing/Workflow/bug_triage_guidelines.md index 8ef2466..f0d4bee 100644 --- a/Redot-Documentation/docs/Contributing/Workflow/bug_triage_guidelines.md +++ b/Redot-Documentation/docs/Contributing/Workflow/bug_triage_guidelines.md @@ -59,7 +59,7 @@ currently defined in the Redot repository: class reference. Issues with this label are either for wrong documentation, or are user-reported "bugs" that are actually limitations to be further documented. Often paired with *Discussion*. Issues related to the ReadTheDocs documentation - should be filed on the [Redot-docs](https://github.com/redot-engine/redot-docs-site) repository. + should be filed on the [Redot-Documentation](https://github.com/redot-engine/Redot-Documentation) repository. - *Enhancement*: describes a proposed enhancement to an existing functionality. - *Feature proposal*: describes a wish for a new feature to be @@ -69,7 +69,7 @@ currently defined in the Redot repository: PRs which add new features but do not have a corresponding proposal use this label. - *For PR meeting*: the issue needs to be discussed in a pull request meeting. - These meetings are public and are held on the [Redot Contributors Chat](https://chat.redotengine.org/). + These meetings are public and are held on the [Redot Discord Server](https://discord.com/invite/redot). - *Good first issue*: the issue is *assumed* to be an easy one to fix, which makes it a great fit for new contributors who want to become familiar with the code base. It should be removed while an active PR is available, that @@ -152,7 +152,7 @@ Android and Linux exclusively, select those two platforms). ### Documentation labels -In the [documentation repository](https://github.com/redot-engine/redot-docs-site), we +In the [documentation repository](https://github.com/redot-engine/Redot-Documentation), we use the following [labels](https://github.com/redot-engine/redot-docs-site/labels): - *Archived*: either a duplicate of another issue, or invalid. Such an diff --git a/Redot-Documentation/docs/Contributing/Workflow/first_steps.md b/Redot-Documentation/docs/Contributing/Workflow/first_steps.md index 3d2f66c..f8a478f 100644 --- a/Redot-Documentation/docs/Contributing/Workflow/first_steps.md +++ b/Redot-Documentation/docs/Contributing/Workflow/first_steps.md @@ -37,12 +37,13 @@ A good place to start is by searching for issues tagged as on GitHub. :::info + Technical details about the PR workflow are outlined in a -specific section, [doc_pr_workflow](pr_workflow.md). +specific section, [doc_pr_workflow](doc_pr_workflow). Details about the code style guidelines and the ``clang-format`` tool used to enforce them are outlined in -[doc_code_style_guidelines](../Development/code_style_guidelines.md). +[doc_code_style_guidelines](doc_code_style_guidelines). ::: @@ -57,9 +58,10 @@ To make sure that your time and efforts aren't wasted, it is recommended to vet first before implementing it and putting it for a review as a PR. To that end, Redot has a [proposal system](https://github.com/redot-engine/redot-proposals). Its usage is encouraged to plan changes and discuss them with the community. Implementation -details can also be discussed with other contributors on the [Redot Contributors Chat](https://chat.redotengine.org/). +details can also be discussed with other contributors on the [Redot Discord Server](https://discord.com/invite/redot). :::note + Proposals are only required when working on an enhancement or a new feature. Bug reports are sufficient for fixing issues. @@ -77,7 +79,7 @@ the development branch and in future maintenance releases. To help with the testing, you have several possibilities: - Compile the engine from source yourself, following the instructions of the - [Compiling](toc-devel-compiling) page for your platform. + [Compiling](doc_introduction_to_the_buildsystem) page for your platform. - Test official pre-release binaries when they are announced (usually on the blog and other community platforms), such as alpha, beta and release candidate (RC) builds. @@ -105,10 +107,12 @@ There are two separate resources referred to as "documentation" in Redot: - **The class reference.** This is the documentation for the complete Redot API as exposed to GDScript and the other scripting languages. It can be consulted - offline, directly in Redot's code editor, or online at Redot :ref:`Class Reference - <doc_class_reference>`. To contribute to the class reference, you have to edit the + + + offline, directly in Redot's code editor, or online at Redot [Class Reference](doc_class_reference). + To contribute to the class reference, you have to edit the XML file corresponding to the class and make a pull request. - See [doc_updating_the_class_reference](../Documentation/updating_the_class_reference.md) and [doc_class_reference_primer](../Documentation/class_reference_primer.md) + See [doc_updating_the_class_reference](doc_updating_the_class_reference) and [doc_class_reference_primer](doc_class_reference_primer) for more details. - **The tutorials and engine documentation and its translations.** @@ -116,7 +120,7 @@ There are two separate resources referred to as "documentation" in Redot: Its contents are generated from plain text files in the reStructured Text (rst) format, to which you can contribute via pull requests on the [Redot-docs](https://github.com/redot-engine/redot-docs-site) GitHub repository. - See [doc_contributing_to_the_documentation](../Documentation/contributing_to_the_documentation.md) for more details. + See [doc_contributing_to_the_documentation](doc_contributing_to_the_documentation) for more details. ## Contributing translations @@ -124,4 +128,4 @@ To make Redot accessible to everyone, including users who may prefer resources in their native language instead of English, our community helps translate both the Redot editor and its documentation in many languages. -See [doc_editor_and_docs_localization](../Documentation/editor_and_docs_localization.md) for more details. \ No newline at end of file +See [doc_editor_and_docs_localization](doc_editor_and_docs_localization) for more details. \ No newline at end of file diff --git a/Redot-Documentation/docs/Contributing/Workflow/pr_review_guidelines.md b/Redot-Documentation/docs/Contributing/Workflow/pr_review_guidelines.md index b009790..d156fa6 100644 --- a/Redot-Documentation/docs/Contributing/Workflow/pr_review_guidelines.md +++ b/Redot-Documentation/docs/Contributing/Workflow/pr_review_guidelines.md @@ -27,13 +27,13 @@ following: 4. Another maintainer reviews the code with a focus on code style/clarity and approves it once satisfied. - 5. A team leader or a member of the `production team - <https://redotengine.org/teams#production>`_ merges the pull request if - satisfied that it has been sufficiently reviewed. + + 5. A team leader or a member of the [production team](https://redotengine.org/teams#production) + merges the pull request if satisfied that it has been sufficiently reviewed. This document will explain steps 2, 3, 4, and 5 in more detail. For a more -detailed explanation of the pull request workflow please see the :ref:`pull -request workflow document <doc_pr_workflow>`. +detailed explanation of the pull request workflow please see the +[pull request workflow document](doc_pr_workflow). :::note @@ -47,6 +47,7 @@ Typically the first interaction on a pull request will be an engine maintainer assigning tags to the pull request and flagging it for review by someone familiar with that area of code. + Engine maintainers are folks who are "members" of the Redot project repository on GitHub and/or are listed on the [Teams page](https://redotengine.org/teams) on the Redot website. Maintainers are responsible for a given area of the @@ -143,6 +144,8 @@ Here are some things to think about and look out for as you review the code: ### 4. Iterate with the contributor and improve the PR + + Maintainers should provide feedback and suggestions for improvement if they spot things in the code that they would like changed. Preferably, suggestions should come in order of importance: first, address overall code design and the approach @@ -159,8 +162,8 @@ want to avoid stringing people along because it feels bad to say "sorry, no". ::: -As you review pull requests, keep the Redot `Code of Conduct -<https://redotengine.org/code-of-conduct>`_ in mind. Especially the following: +As you review pull requests, follow the rules of common decency. +Especially the following: * Politeness is expected at all times. Be kind and courteous. @@ -194,10 +197,9 @@ contributor: as possible. And ultimately, don't feel pressured to deal with the PR all alone. Feel free to -ask for a helping hand on the `Redot Contributors Chat -<https://chat.redotengine.org>`_, in the appropriate channel or in #general. -Other teams may already be tagged for review, so you can also wait or ask for -their assistance. +ask for a helping hand on the [Redot Discord Server](https://discord.com/invite/redot), +in the appropriate channel or in #redot-discussion. Other teams may already be tagged for +review, so you can also wait or ask for their assistance. ### 5. Approve the pull request @@ -229,9 +231,10 @@ review. The important thing is that both the substantive code and the code style need to be reviewed and considered before a pull request is merged. When reviewing code style pay particular attention to ensuring that the pull -request follows the [doc_code_style_guidelines](../Development/code_style_guidelines.md). While ``clang-format`` and -various CI checks can catch a lot of inconsistencies, they are far from perfect -and are unable to detect some issues. For example, you should check that: +request follows the [doc_code_style_guidelines](doc_code_style_guidelines). +While``clang-format`` and various CI checks can catch a lot of inconsistencies, +they are far from perfect and are unable to detect some issues. For example, you +should check that: * The style of header includes is respected. * Identifiers use ``snake_case`` and follow our naming conventions. @@ -299,8 +302,7 @@ Redot organization left a review without having the relevant expertise. An easy way to find PRs that may be ready for merging is filtering by approved PRs and sorting by recently updated. For example, in the main Redot -repository, you can use `this link -<https://github.com/redot-engine/redot-engine/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved+sort%3Aupdated-desc>`_. +repository, you can use [this link](https://github.com/redot-engine/redot-engine/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved+sort%3Aupdated-desc) ::: @@ -331,7 +333,7 @@ out more broadly to ask for help reviewing. Consider asking: * **Make sure that the PR has no merge conflicts.** Contributors may need to rebase their changes on top of the relevant branch - (e.g. ``master`` or ``3.x``) and manually fix merge conflicts. Even if there + (e.g. ``master`` or ``4.x``) and manually fix merge conflicts. Even if there are no merge conflicts, contributors may need to rebase especially old PRs as the GitHub conflict checker may not catch all conflicts, or the CI may have changed since it was originally run. @@ -354,31 +356,31 @@ out more broadly to ask for help reviewing. Consider asking: While we don't have a very strict ruleset for commit messages, we still require them to be short yet descriptive and use proper English. As a maintainer you've probably written them enough times to know how to make one, - but for a general template think about *"Fix <issue> in <part of codebase>"*. - For a more detailed recommendation see the `contributing.md - <https://github.com/redot-engine/redot-engine/blob/master/CONTRIBUTING.md#format-your-commit-messages-with-readability-in-mind>`_ + but for a general template think about *"Fix \; in \;"*. + For a more detailed recommendation see the [contributing](https://github.com/redot-engine/redot-engine/blob/master/CONTRIBUTING.md#format-your-commit-messages-with-readability-in-mind) page in the main Redot repository. ### 4. GitHub checklist * **Validate the target branch of the PR.** + Most Redot development happens around in the ``master`` branch. Therefore most pull requests must be made against it. From there pull requests can then be backported to other branches. Be wary of people making PRs on the version they - are using (e.g, ``3.3``) and guide them to make a change against a - higher-order branch (e.g. ``3.x``). If the change is not applicable for the + are using (e.g, ``26.1``) and guide them to make a change against a + higher-order branch (e.g. ``26.x``). If the change is not applicable for the ``master`` branch, the initial PR can be made against the current maintenance - branch, such as ``3.x``. It's okay for people to make multiple PRs for each + branch, such as ``26.x``. It's okay for people to make multiple PRs for each target branch, especially if the changes cannot be easily backported. Cherry-picking is also an option, if possible. Use the appropriate labels if - the PR can be cherrypicked (e.g. ``cherrypick:3.x``). + the PR can be cherrypicked (e.g. ``cherrypick:26.x``). :::note It is possible to change the target branch of the PR, that has already been submitted, but be aware of the consequences. As it cannot be synchronized -with the push, the target branch change will inevitable tag the entire list +with the push, the target branch change will inevitably tag the entire list of maintainers for review. It may also render the CI incapable of running properly. A push should help with that, but if nothing else, recommend opening a new, fresh PR. @@ -395,7 +397,7 @@ opening a new, fresh PR. target branch change). Similarly, when merging a PR with a higher milestone than the current version, - or a "wildcard" milestone (e.g. "4.x"), ensure to update the milestone to the + or a "wildcard" milestone (e.g. ``26.x``), ensure to update the milestone to the current version. * **Make sure that the opening message of the PR contains the @@ -412,7 +414,7 @@ opening a new, fresh PR. relevant milestone.** In other words, if the PR is targeting the ``master`` branch, but is then also - cherrypicked for ``3.x``, the next ``3.x`` release would be the appropriate + cherrypicked for ``26.x``, the next ``26.x`` release would be the appropriate milestone for the closed issue. ### 5. Merge the pull request diff --git a/Redot-Documentation/docs/Contributing/Workflow/pr_workflow.md b/Redot-Documentation/docs/Contributing/Workflow/pr_workflow.md index 96b165d..5255efb 100644 --- a/Redot-Documentation/docs/Contributing/Workflow/pr_workflow.md +++ b/Redot-Documentation/docs/Contributing/Workflow/pr_workflow.md @@ -1,8 +1,6 @@ # Pull request workflow -.. highlight:: shell - The so-called "PR workflow" used by Redot is common to many projects using Git, and should be familiar to veteran free software contributors. The idea is that only a small number (if any) commit directly to the *master* branch. @@ -29,7 +27,7 @@ issue tracker and PR system. :::note If you are contributing to the documentation, its repository can -be found [here](https://github.com/redot-engine/redot-docs-site). +be found [here](https://github.com/redot-engine/Redot-Documentation). ::: @@ -54,16 +52,17 @@ You can also try out [GitHub's interactive guide](https://try.github.io/). The branches on the Git repository are organized as follows: + - The ``master`` branch is where the development of the next major version occurs. As a development branch, it can be unstable and is not meant for use in production. This is where PRs should be done in priority. -- The stable branches are named after their version, e.g. ``3.1`` and ``2.1``. +- The stable branches are named after their version, e.g. ``4.3`` and ``26.2``. They are used to backport bugfixes and enhancements from the ``master`` - branch to the currently maintained stable release (e.g. 3.1.2 or 2.1.6). + branch to the currently maintained stable release (e.g. 4.2 or 26.2). As a rule of thumb, the last stable branch is maintained until the next - minor version (e.g. the ``3.0`` branch was maintained until the release of - Redot 3.1). + minor version (e.g. the ``26.1`` branch was maintained until the release of + Redot ``26.2``). If you want to make PRs against a maintained stable branch, please check first if your changes are also relevant for the ``master`` branch, and if so make the PR for the ``master`` branch in priority. Release managers can then @@ -73,17 +72,17 @@ The branches on the Git repository are organized as follows: ## Forking and cloning -The first step is to *fork* the [Redotengine/Redot](https://github.com/redot-engine/redot) +The first step is to *fork* the [redot-engine](https://github.com/redot-engine/redot-engine) repository on GitHub. To do so, you will need to have a GitHub account and to be logged in. In the top right corner of the repository's GitHub page, you should see the "Fork" button as shown below: -![Image](img/github_fork_button.png) +![Image](img/Contributing/Workflow/github_fork_button.png) Click it, and after a while you should be redirected to your own fork of the Redot repo, with your GitHub username as namespace: -![Image](img/github_fork_url.png) +![Image](img/Contributing/Workflow/github_fork_url.png) You can then *clone* your fork, i.e. create a local copy of the online repository (in Git speak, the *origin remote*). If you haven't already, @@ -91,6 +90,7 @@ download Git from [its website](https://git-scm.com) if you're using Windows or macOS, or install it through your package manager if you're using Linux. :::note + If you are on Windows, open Git Bash to type commands. macOS and Linux users can use their respective terminals. @@ -99,11 +99,11 @@ can use their respective terminals. To clone your fork from GitHub, use the following command: ``` -git clone https://github.com/USERNAME/Redot +git clone https://github.com/USERNAME/redot-engine ``` -After a little while, you should have a ``Redot`` directory in your current +After a little while, you should have a ``redot-engine`` directory in your current working directory. Move into it using the ``cd`` command: ``` @@ -114,21 +114,22 @@ cd Redot We will start by setting up a reference to the original repository that we forked: ``` -git remote add upstream https://github.com/redot-engine/redot +git remote add upstream https://github.com/redot-engine/redot-engine git fetch upstream ``` This will create a reference named ``upstream`` pointing to the original -``Redotengine/Redot`` repository. This will be useful when you want to pull new +``redot-engine/redot-engine`` repository. This will be useful when you want to pull new commits from its ``master`` branch to update your fork. You have another -remote reference named ``origin``, which points to your fork (``USERNAME/Redot``). +remote reference named ``origin``, which points to your fork (``USERNAME/redot-engine``). You only need to do the above steps once, as long as you keep that local -``Redot`` folder (which you can move around if you want, the relevant +``redot-engine`` folder (which you can move around if you want, the relevant metadata is hidden in its ``.git`` subfolder). :::note + *Branch it, pull it, code it, stage it, commit, push it, rebase it... technologic.* @@ -231,6 +232,7 @@ You will then be back to the original state of your branch before calling ``git pull --rebase``. :::note + If you omit the ``--rebase`` argument, you will instead create a merge commit which tells Git what to make of the two distinct branches. If any conflicts arise, they would be resolved all at once via this merge commit. @@ -248,15 +250,17 @@ changes are easy to review and understand long after they have been merged. ::: + If you have already created a merge commit without using ``rebase``, or have made any other changes that have resulted in undesired history, the best option -is to use an *interactive rebase* on the upstream branch. See the :ref:`dedicated -section <doc_pr_workflow_rebase>` for instructions. +is to use an *interactive rebase* on the upstream branch. See the +[dedicated section](doc_pr_workflow_rebase) for instructions. :::tip + If at any time you want to *reset* a local branch to a given commit or branch, -you can do so with `[git reset --hard](commit ID)` or -``git reset --hard <remote>/<branch>`` (e.g. ``git reset --hard upstream/master``). +you can do so with ``git reset --hard `` or +``git reset --hard /;`` (e.g. ``git reset --hard upstream/master``). Be warned that this will remove any changes that you might have committed in this branch. If you ever lose commits by mistake, use the ``git reflog`` command @@ -281,14 +285,15 @@ bring changes from the working directory to the Git repository, you need to There are various commands you should know to review your current work, before staging it, while it is staged, and after it has been committed. + - ``git diff`` will show you the current unstaged changes, i.e. the differences between your working directory and the staging area. -- `[git checkout --](files)` will undo the unstaged changes to the given +- ``git checkout -- (files)`` will undo the unstaged changes to the given files. -- `[git add](files)` will *stage* the changes on the listed files. +- ``git add (files)`` will *stage* the changes on the listed files. - ``git diff --staged`` will show the current staged changes, i.e. the differences between the staging area and the last commit. -- `[git reset HEAD](files)` will *unstage* changes to the listed files. +- ``git reset HEAD (files)`` will *unstage* changes to the listed files. - ``git status`` will show you what are the currently staged and unstaged modifications. - ``git commit`` will commit the staged files. It will open a text editor @@ -369,8 +374,7 @@ Git will ask you for your username and password. For your password, enter your GitHub Personal Access Token (PAT). If you do not have a GitHub Personal Access Token, or do not have one with the correct permissions for your newly forked repository, you will need to create one. Follow this link to create your Personal -Access Token: `Creating a personal access token -<https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>`_. +Access Token: [Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) After you have successfully verified your account using your PAT, the changes will be sent to your remote repository. If you check the fork's page on GitHub, @@ -379,18 +383,18 @@ you should see a new branch with your added commits. ## Issuing a pull request When you load your fork's branch on GitHub, you should see a line saying -*"This branch is 2 commits ahead of Redotengine:master."* (and potentially some +*"This branch is 2 commits ahead of redot-engine:master."* (and potentially some commits behind, if your ``master`` branch was out of sync with the upstream ``master`` branch). -![Image](img/github_fork_make_pr.png) +![Image](img/Contributing/Workflow/github_fork_make_pr.png) On that line, there is a "Pull request" link. Clicking it will open a form -that will let you issue a pull request on the ``Redotengine/Redot`` upstream +that will let you issue a pull request on the ``redot-engine/redot-engine`` upstream repository. It should show you your two commits, and state "Able to merge". If not (e.g. it has way more commits, or says there are merge conflicts), don't create the PR yet, something went wrong. Go to our -[Redot Contributors Chat](https://chat.redotengine.org/) and ask for support :) +[discord server](https://discord.com/invite/redot) and ask for support :) Use an explicit title for the PR and put the necessary details in the comment area. You can drag and drop screenshots, GIFs or zipped projects if relevant, @@ -475,6 +479,7 @@ git rebase -i upstream/master ``` :::note + Referencing branches in Git is a bit tricky due to the distinction between remote and local branches. Here, ``upstream/master`` (with a `/`) is a local branch which has been pulled from the ``upstream`` @@ -559,7 +564,7 @@ and tedious. Fortunately ``git`` has a command just for this situation, ``git re If your PR was created from the ``4.2`` branch and you want to update it to instead start at ``master`` the following steps *should* fix this in one step: -```text +``` git rebase -i --onto master 4.2 ``` diff --git a/Redot-Documentation/docs/Contributing/Workflow/testing_pull_requests.md b/Redot-Documentation/docs/Contributing/Workflow/testing_pull_requests.md index e3313b0..bd1f64e 100644 --- a/Redot-Documentation/docs/Contributing/Workflow/testing_pull_requests.md +++ b/Redot-Documentation/docs/Contributing/Workflow/testing_pull_requests.md @@ -1,3 +1,4 @@ + # Testing pull requests @@ -29,23 +30,23 @@ instead. - Open the pull request page. Click the **Checks** tab near the top of the page: -![Image](img/testing_pull_requests_access_checks.webp) +![Image](img/Contributing/Workflow/testing_pull_requests_access_checks.webp) - Click the **Artifacts** dropdown on the right of the page: -![Image](img/testing_pull_requests_checks_artifacts.webp) +![Image](img/Contributing/Workflow/testing_pull_requests_checks_artifacts.webp) - In the dropdown, click the artifact's name to download it. Remember to scroll if you cannot see the name of the platform you're looking for: -![Image](img/testing_pull_requests_checks_artifacts_list.webp) +![Image](img/Contributing/Workflow/testing_pull_requests_checks_artifacts_list.webp) - Extract the ZIP archive then run the executable. Note that Windows and macOS binaries are **not** code signed. This means you may have to bypass a security warning before you can run the executable. On Windows, if you frequently test pull request builds, it may be better to disable Windows SmartScreen permanently in the Windows security settings. - On macOS, see [doc_running_on_macos](../../tutorials/export/running_on_macos.md) for instructions on bypassing Gatekeeper. + On macOS, see [doc_running_on_macos](doc_running_on_macos) for instructions on bypassing Gatekeeper. ### If you don't have a GitHub account @@ -55,7 +56,7 @@ to generate a universal download link. - Open the pull request page. Click the *fork*'s branch name near the top of the page: -![Image](img/testing_pull_requests_access_fork.png) +![Image](img/Contributing/Workflow/testing_pull_requests_access_fork.png) - Now that you are on the fork's branch page, click the ``.github`` folder at the top of the file list. Then, click on the ``workflows`` folder (which is inside the ``.github`` folder). @@ -68,7 +69,7 @@ to generate a universal download link. If the format of the URL you pasted is correct, you should be presented with a page like this: -![Image](img/testing_pull_requests_nightly_link.png) +![Image](img/Contributing/Workflow/testing_pull_requests_nightly_link.png) - Click the URL of the artifact you wish to download. @@ -88,14 +89,14 @@ by Redot's GitHub Actions setup. - Open the pull request page. Click the *fork*'s branch name near the top of the page: -![Image](img/testing_pull_requests_access_fork.png) +![Image](img/Contributing/Workflow/testing_pull_requests_access_fork.png) - Now that you are on the fork's branch page, click the green **Code** button on the right of the page then choose **Download ZIP** in the dropdown: -![Image](img/testing_pull_requests_fork_zip.png) +![Image](img/Contributing/Workflow/testing_pull_requests_fork_zip.png) -- Extract the ZIP archive and follow the [compiling](toc-devel-compiling) instructions +- Extract the ZIP archive and follow the [compiling](doc_introduction_to_the_buildsystem) instructions for your operating system. ### Checking out a pull request branch with git @@ -105,7 +106,7 @@ Alternatively, you can checkout the pull request directly with git: - Open the pull request page. Note the pull request *number* (``PR_NUMBER``), and the *branch name* (``BRANCH_NAME``), but without the user name. -![Image](img/testing_pull_requests_command_line_checkout.webp) +![Image](img/Contributing/Workflow/testing_pull_requests_command_line_checkout.webp) - Construct the command using this pattern: