├── .github └── ISSUE_TEMPLATE │ ├── config.yml │ └── feature_proposal.yml ├── LICENSE.txt ├── README.md └── TRIAGE-AND-REVIEW.md /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | # All proposals must follow the template, so disallow creating blank issues. 2 | blank_issues_enabled: false 3 | 4 | contact_links: 5 | - name: Share and discuss ideas 6 | url: https://github.com/godotengine/godot-proposals/discussions 7 | about: Discuss any idea related to improving Godot 8 | 9 | - name: Main Godot repository 10 | url: https://github.com/godotengine/godot 11 | about: Report bugs on the main Godot repository 12 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_proposal.yml: -------------------------------------------------------------------------------- 1 | name: Feature implementation proposal 2 | description: Propose a possible solution to solve an engine limitation 3 | body: 4 | 5 | - type: markdown 6 | attributes: 7 | value: | 8 | - Write a descriptive proposal title above. 9 | - Search [open](https://github.com/godotengine/godot-proposals/issues) and [closed](https://github.com/godotengine/godot-proposals/issues?q=is%3Aissue+is%3Aclosed) proposals to ensure the feature has not already been suggested. 10 | 11 | - type: textarea 12 | attributes: 13 | label: Describe the project you are working on 14 | description: This is important to know the *context* in which the feature is being proposed. Features used in real-world projects are more likely to be added. 15 | placeholder: Example - "A 3D space game with heavy use of cut-out animation" 16 | validations: 17 | required: true 18 | 19 | - type: textarea 20 | attributes: 21 | label: Describe the problem or limitation you are having in your project 22 | placeholder: Example - "The 3D selection tools are cumbersome to use." 23 | validations: 24 | required: true 25 | 26 | - type: textarea 27 | attributes: 28 | label: Describe the feature / enhancement and how it helps to overcome the problem or limitation 29 | placeholder: Example - "Add keyboard shortcuts to select groups of nodes quickly." 30 | validations: 31 | required: true 32 | 33 | - type: textarea 34 | attributes: 35 | label: Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams 36 | placeholder: Example - "When the user presses Ctrl + Shift + G, select all nodes that have the group..." 37 | validations: 38 | required: true 39 | 40 | - type: textarea 41 | attributes: 42 | label: If this enhancement will not be used often, can it be worked around with a few lines of script? 43 | placeholder: Example - "This can be worked around with an editor plugin, but it is not particularly convenient." 44 | validations: 45 | required: true 46 | 47 | - type: textarea 48 | attributes: 49 | label: Is there a reason why this should be core and not an add-on in the asset library? 50 | placeholder: Example - "This is about improving the 3D editor usability out of the box." 51 | validations: 52 | required: true 53 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) 2019-present Godot Engine contributors. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all 11 | copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 19 | SOFTWARE. 20 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Godot Improvement Proposals 2 | 3 | This repository serves as the central hub for proposing, discussing, and 4 | reviewing new features and enhancements in Godot Engine. While there exists 5 | some leeway, most changes made to the engine must go through the proposal 6 | process first. The goal is to determine whether the suggestion makes sense 7 | for the majority of Godot users, and to figure out the best approach to 8 | implement it. 9 | 10 | As such, everyone is welcome to participate in ongoing discussions, or start 11 | a new one. 12 | 13 | > **Tip:** Use the [Godot proposals viewer](https://godot-proposals-viewer.github.io/) 14 | > to view all open proposals on a single page. This allows for easy searching 15 | > in proposal titles using Ctrl + F or Cmd + F. 16 | 17 | Bug reports are not a subject of the proposal process. If you experience 18 | an issue while using Godot that cannot be attributed to a missing feature, 19 | please open a report in the [main Godot repository](https://github.com/godotengine/godot). 20 | Feel free to open a pull-request based on any bug report as well! 21 | 22 | ## Suggesting improvements 23 | 24 | You have two options to make a suggestion for the future of the engine. You 25 | can either open a proposal [**Issue**](https://github.com/godotengine/godot-proposals/issues/new/choose), 26 | or you can create an open [**Discussion**](https://github.com/godotengine/godot-proposals/discussions/new). 27 | 28 | Proposal *issues* are required to explain in technical detail how the suggested change 29 | should be implemented. It is also preferred that the submitter of a proposal is 30 | ready to implement it if it was approved. If you have a more general idea for 31 | a feature but are not well versed in Godot's architecture or do not possess 32 | the necessary knowledge to implement it in the engine, feel free to open a 33 | [*discussion*](https://github.com/godotengine/godot-proposals/discussions/new) 34 | instead of an [*issue*](https://github.com/godotengine/godot-proposals/issues/new/choose). 35 | 36 | A valid feature proposal will be held open to allow fellow Godot users and 37 | contributors to weigh in on the suggestion and its implementation. While all 38 | opinions are considered, a core developer must approve the feature and its 39 | implementation for a proposal to be considered ready to implement. 40 | 41 | **Proposals should be made by opening an issue or a discussion, not a pull request.** 42 | Don't fork this repository to open a proposal. 43 | 44 | ## Rules for submitting a proposal 45 | 46 | > **Note:** The following points describe requirements for a proposal issue. A 47 | > [discussion](https://github.com/godotengine/godot-proposals/discussions/new), 48 | > on the other hand, can be started in any form. 49 | 50 | 1. Only proposals that properly fill out the template will be considered. If 51 | the template is not filled out or is filled out improperly, it will be closed. 52 | 53 | 2. Please open one proposal per feature requested. Do not cram multiple feature 54 | requests in a single proposal, as this makes it harder to discuss features 55 | individually. 56 | 57 | 3. All proposals must be linked to a substantive use-case. In justifying your 58 | proposal, it is not enough to say it would be "nice" or "helpful". Use the 59 | template to show how Godot is not currently meeting your needs and then 60 | explain how your proposal will meet a particular need. 61 | 62 | * If you feel that you cannot provide highly detailed instructions with the 63 | proposal, consider creating a more simple, open-ended issue in the 64 | unofficial, community-maintained 65 | [Godot Ideas](https://github.com/godot-extended-libraries/godot-ideas) 66 | repository. 67 | 68 | 4. Other users must express interest in your proposal for it to be considered. 69 | Godot is community-driven: if no other users are interested in your proposal, 70 | it may be closed. It is up to you to draw interest in your proposed feature. 71 | Start by reaching out on the community channels (Reddit, Discord, 72 | [Godot Contributors Chat](https://chat.godotengine.org/)), etc. 73 | see the [Community Channels](http://docs.godotengine.org/en/stable/community/channels.html) doc), 74 | then create your proposal once you have gained some interest. 75 | 76 | 5. You can make a PR implementing the feature in the main repository before 77 | making a proposal. However, if it is a large change, a core developer may 78 | require that you make a proposal before your PR can be merged. It is always 79 | better to make and discuss a proposal before spending your time implementing 80 | a new feature. 81 | 82 | 6. If you or another user is capable of making a PR, include that fact in 83 | the issue or in a subsequent comment so that a core contributor can 84 | fast-track the approval process. 85 | 86 | ## What to do if your proposal is closed 87 | 88 | If your proposal was closed because the template was not filled out, then 89 | fill out the [template](.github/ISSUE_TEMPLATE/feature_proposal.yml) 90 | and ask the person who closed the issue to re-open it. 91 | 92 | If your proposal was closed as a duplicate and had a different approach to solving 93 | the problem described in the linked proposal, please comment in the linked proposal 94 | with your own idea. You don't need to copy-paste your whole proposal's text. Instead, 95 | rephrase the main ideas and add mockups if needed. 96 | 97 | If your proposal was closed because of lack of interest, then try to build up 98 | some interest on the [community channels](http://docs.godotengine.org/en/stable/community/channels.html) 99 | and then ask the person who closed the issue to re-open it. 100 | 101 | If your proposal was closed because a core contributor determined that it was 102 | not worth pursuing and you feel that it was wrongly closed, then feel free 103 | to join the [Godot Contributors Chat](https://chat.godotengine.org/) 104 | and have a more in-depth discussion with other core developers about the feature. 105 | 106 | ## How core developers evaluate proposals 107 | 108 | The following is a list of considerations that core developers use when deciding 109 | to accept, close, or leave a proposal open. It is intended to be useful for core 110 | developers when considering proposals and for proposal-makers in drafting their 111 | proposals. 112 | 113 | #### 1. Does the proposal comply with the rules? 114 | 115 | Read the proposal and check to see that it complies with the above-stated rules. 116 | If it does not, close the proposal. 117 | 118 | #### 2. How much support is the proposal receiving? 119 | 120 | Evaluate the amount of support the proposal is receiving. This is an ongoing 121 | analysis. If a proposal receives little support at first, it may receive 122 | additional support later on. 123 | 124 | #### 3. Can this proposal be implemented with an addon? 125 | 126 | Evaluate whether it is possible for the proposal to be implemented in an addon. 127 | If it is possible for the proposal to be in an addon, it is less likely to be 128 | accepted. 129 | 130 | #### 4. Does this proposal benefit most users? 131 | 132 | Determine whether this proposal benefits all users, or just certain users. 133 | For example, a feature that can only be used for 3D FPS games is less 134 | likely to be accepted than a feature that benefits all 3D games. 135 | 136 | #### 5. Can this proposal be implemented in a robust, general-purpose way? 137 | 138 | Determine whether the feature can be implemented in a robust way that benefits 139 | all use-cases. For example, many games use an inventory system, but every game 140 | implements inventory differently. Accordingly, a proposal for an inventory 141 | system will likely not be accepted because it would be impossible for us to 142 | implement an inventory system that works for most users that need an inventory 143 | in their game. 144 | 145 | #### 6. Does this proposal help users overcome a limitation? 146 | 147 | Proposals that overcome a specific limitation are more likely to be accepted 148 | than proposals that are just helpful. In short, need-to-have features will be 149 | prioritized over nice-to-have features. Further, the core developers prioritize 150 | changes that enable users to implement features themselves over implementing 151 | those same features in core. 152 | 153 | #### 7. How complex would the proposed feature be? 154 | 155 | A highly complex new feature involving substantial changes to core is less likely 156 | to be accepted than a feature that can be contained within a single node, or a 157 | group of nodes. 158 | 159 | #### 8. Can the feature be worked around in script with a few lines? 160 | 161 | If the feature is only intended to save users a few lines of code it is unlikely 162 | to be accepted. 163 | 164 | The above considerations are all balanced, no one is more important than another. 165 | Core developers have discretion to weigh the factors as they see fit. 166 | 167 | In addition to the above guideline, consider [this article](https://docs.godotengine.org/en/latest/community/contributing/best_practices_for_engine_contributors.html) 168 | which outlines what core developers consider when evaluating PRs. 169 | -------------------------------------------------------------------------------- /TRIAGE-AND-REVIEW.md: -------------------------------------------------------------------------------- 1 | ## Triaging Godot proposals 2 | 3 | When a new proposal is added, it needs to be triaged. Existing proposals sometimes require 4 | re-triaging as well. The main goal of triaging a proposal is: 5 | 6 | * to evaluate if it follows formal submission rules described in the readme; 7 | * to make sure it is not a duplicate or otherwise invalid entry; 8 | * to assign appropriate labels to it. 9 | 10 | Labels describe engine areas and map exactly to the labels we use in the main repository. 11 | Sometimes, new labels are added which fit existing proposals, so additional triaging 12 | may be necessary. 13 | 14 | Triagers don't need to personally evaluate the merits of the proposed feature. They can, 15 | however, close a proposal immediately if it's not valid, is missing key details, or is 16 | a duplicate. Partial duplicates can be left open at triager's discretion, or can be linked 17 | with an existing discussion. 18 | 19 | To help track proposals, plan future work, and organize review meetings, we use a dedicated 20 | GitHub project: 21 | 22 | https://github.com/orgs/godotengine/projects/37 23 | 24 | Triagers need to add the new proposal to this project, set its "**Status**" to "_In Discussion_" and 25 | its "**Feature Concept**" and "**Proposed Implementation**" fields to "_Unassessed_". 26 | 27 | ## Reviewing Godot proposals 28 | 29 | Each proposal review starts with a public discussion. Stakeholders, area maintainers, as well as 30 | users of the engine can participate in the discourse, support or raise concern and try to 31 | forge the initial draft of a feature into a shape that solves the problem for the majority of users. 32 | 33 | > See Godot documentation to learn about [the engine design philosophy](https://docs.godotengine.org/en/stable/community/contributing/best_practices_for_engine_contributors.html). 34 | 35 | For some areas of the engine, area maintainers can decide on the feature during this period of public 36 | discussion. In a lot of cases, though, the proposal can be put for review during a proposal review 37 | meeting. 38 | 39 | In addition to being reviewed by the maintainers and the community, some proposals may require to be 40 | reviewed by the engine core team specifically. For such cases, there is a special label that is assigned 41 | to such proposal issues: ![requires core feedback](https://img.shields.io/badge/-requires%20core%20feedback-E06006.svg). 42 | 43 | ### Statuses 44 | 45 | Proposals tracked in the aforementioned GitHub project can have one of the following statuses: 46 | 47 | * In Discussion 48 | * Ready for Review 49 | * On Hold 50 | * Ready for Implementation 51 | * Implemented 52 | * Not Planned 53 | 54 | Proposals start by being "_In Discussion_" and can return to that status later if further public 55 | deliberation is required. Once a proposal has reached a critical mass of discussion, or sufficient 56 | time has passed, it can be marked as "_Ready for Review_". At this point members of relevant engine 57 | teams can pass their judgement on both feature concept and technical implementation. If a more 58 | open maintainers discussion is required, future proposal review meetings can also be used 59 | (as far as time allows, of course). 60 | 61 | Proposals that are approved in every way are marked as "_Ready for Implementation_". Priority is 62 | given to those proposals which have an appointed implementer. Under the best circumstances, the 63 | person who opens the proposal is the one who is going to implement it. But in practice it can be 64 | anyone willing to step forward. We use the "**Assignee**" field on the proposal issue to track the 65 | implementer. If at this point the proposal does not have an implementer, a label can be used to 66 | call for contributors: ![implementer wanted](https://img.shields.io/badge/-implementer%20wanted-02955E.svg). 67 | 68 | Rejected proposals are marked as "_Not Planned_". The exact reason can vary a lot, so this 69 | status is all encompassing. The details can be explained in the closing message from a maintainer, 70 | as well as expressed with appropriate "**Feature Concept**" and "**Proposed Implementation**" status. 71 | 72 | A proposal can be put "_On Hold_" if it depends on another feature to be implemented first, it 73 | requires more time from the author, or if the decision was postponed until a future version of Godot. 74 | 75 | "_Implemented_" is self-explanatory. Note, that a proposal may still be open even if it marked as implemented. 76 | In such a case this indicates that while the feature has not been merged yet, it is complete 77 | and new PRs are not required. 78 | 79 | ### Feature Concept 80 | 81 | The "**Feature Concept**" field is used to indicate if the proposed solution, conceptually, fits Godot. 82 | This is different from approving the implementation. When the feature is approved it means that 83 | the problem described by the proposal is considered valid and that it is worth solving. It also means 84 | that the solution must be provided by the Godot engine team. This can mean a core change, or 85 | an _official_ extension. 86 | 87 | "**Feature Concept**" can have following values: 88 | 89 | * Unassessed 90 | * Needs User Feedback 91 | * Approved 92 | * Rejected: Out of Scope 93 | * Rejected: Lacks Significance 94 | 95 | Initially, the feature is "_Unassessed_" until a decision is reached by qualified maintainers. This 96 | can happen during a proposal review meeting, or a team meeting. In some cases, this can happen during 97 | the open discussion. 98 | 99 | If the proposal may have merits, but use cases are not completely clear, it can be marked as 100 | "_Needs User Feedback_" to give more opportunities for feedback. However, if merits of the proposal 101 | are not obvious (e.g. the use case is too specific, there is not enough public support, etc.), 102 | then it is rejected with "_Lacks Significance_". 103 | 104 | Proposals can have merits but still be rejected if they don't fit into the overall design of the engine. 105 | In an effort to make engine maintenance sustainable and avoid technical debt accumulating too quickly, 106 | only solutions that are beneficial to a lot of users can be considered most of the time. If the 107 | described problem is better solved by third-party tools or user-space solutions, the proposal is 108 | rejected with "_Out of Scope_". 109 | 110 | > Rejected proposals can be reopened if more information is provided by users, so if a particular 111 | > use case is important to you, do not hesitate to leave a comment about it! 112 | 113 | "_Approved_" is self-explanatory, but should not be mistaken for the overall "_Ready for Implementation_" status. 114 | It only means that the feature itself is favorably reviewed for its inclusion into the engine. 115 | 116 | ### Proposed Implementation 117 | 118 | The "**Proposed Implementation**" field indicates if the exact technical solution to the problem 119 | is acceptable. This is different from approving the feature, and is not the same as code review. 120 | When the implementation is approved, it means that from the technical standpoint this is a good 121 | solution and it seems appropriate for the overall design of the engine. 122 | 123 | "**Proposed Implementation**" can have following values: 124 | 125 | * Unassessed 126 | * Needs Changes 127 | * Pending Engine Changes 128 | * Approved 129 | * Rejected: Lacks Consensus 130 | 131 | Just like the feature, the implementation starts off as "_Unassessed_". If during a review 132 | maintainers agree on the implementation, it gets "_Approved_". It is likely that at 133 | this point the implementation can be done, but do check the overall status. 134 | 135 | Alternatively, some changes may be required from the implementer. "_Needs Changes_" is used 136 | in such cases, but it is also possible that the proposal is fully approved anyway. This must 137 | be reflected in maintainers' comments in the proposal itself. 138 | 139 | Sometimes, the implementation may depend on the engine changes that aren't merged yet. 140 | "_Pending Engine Changes_" can be used to indicate that, likely with the "_On Hold_" status 141 | of the proposal. 142 | 143 | Typically, if the feature has already been accepted, we want to also accept the implementation. 144 | But it is not always possible to find a solution fitting the needs of the majority. When 145 | the proposal becomes controversial and no apparent side seems to have the upper hand, 146 | we unfortunately often have to reject it with "_Lacks Consensus_". We believe that in 147 | such cases, not changing the status quo is more important than implementing a feature that 148 | doesn't have complete support or has strong opposition. 149 | 150 | > As mentioned before, even if the proposal was rejected, it can be reopened in the future. 151 | > With controversial proposals, however, it is better to wait some time before restarting the 152 | > discussion. This allows everyone to reset a bit and have a fresher perspective on the 153 | > situation. As well as gives time for new voices to appear with their opinions. 154 | 155 | ### The GitHub Project 156 | 157 | The GitHub project used to track proposals is here: 158 | 159 | https://github.com/orgs/godotengine/projects/37 160 | 161 | It has several board views that allow to quickly find the issues that need to be discussed or can be 162 | implemented. It also gives a complete look for slices based on "**Status**", "**Feature Concept**", 163 | and "**Proposed Implementation**". Any organization member can add issues to be tracked there, 164 | so please use it responsibly and don't forget to assign correct values if you do so. 165 | 166 | You can add an issue to the project from the issue's page directly. Use the gear icon in the sidebar 167 | next to the "**Projects**" title and select "_Godot Proposal Metaverse_" from the list of available projects. 168 | Status is automatically set to the default value, "_In Discussion_", even though it doesn't update visibly. 169 | You can still set it, or set it to another appropriate value. 170 | 171 | > Don't forget to unfold the project panel in the sidebar and set up the other two fields under the cutoff. 172 | > Click the chevron arrow next to the project name, or the "**+3 more**" text. Then select the 173 | > appropriate values for both feature and implementation from their lists. 174 | 175 | You can find all the issues in the project using this search filter: 176 | 177 | https://github.com/godotengine/godot-proposals/issues?q=is%3Aopen+is%3Aissue+project%3Agodotengine%2F37 178 | 179 | You can find all the issues **not** in the project yet using this search filter: 180 | 181 | https://github.com/godotengine/godot-proposals/issues?q=is%3Aopen+is%3Aissue+-project%3Agodotengine%2F37 182 | --------------------------------------------------------------------------------