Skript Enhancement Proposals

# Skript Enhancement Proposals :::warning This is the template for all other proposals. If you're drafting your own proposal, you can copy the example from [here](#The-Proposal-Format). The blue **info** boxes contain short descriptions explaining the purpose of each section. ::: :::info A simple table of meta details (e.g. who came up with this, what state is it in, etc.) ::: ||| |-------:|:-------| |Creator|@Moderocky| |Type|Procedure| |Status|Active| |Created|04/24| ## Summary :::info A quick, 'too long; didn't read' summary of the proposal. This is just a sentence or two about what it is and what it aims to achieve. ::: A standardised layout and system for documenting large feature or systemic proposals, as well as the. ## Introduction ### Goals :::info Bullet-point notes about what the proposal aims to achieve. It is very important for proposals to have clear goals so that they don't end up straying from the plan during their implementation. Goals also give us an easy way to judge whether a proposal is successful. ::: - To make sure important changes are properly explained. - To make sure the results of historic discussions are preserved and organised. - To make sure proposals are clearly detailed and properly thought-through. ### Non-Goals :::info An __optional__ section. The 'non-goals' are a list of things a proposal *isn't* trying to do. A proposal's non-goals are typically things that a person could easily mistake for being in-scope or might think are similar. They help us not to get confused when (mis)reading a proposal. ::: - This is not designed to replace internal discussion. - This is not designed to replace the GitHub suggestions tracker or discussions tab, or any other forum of discussion. - This is not designed for documenting minor features or syntax changes. ### Motivations :::info A short section for explaining why this proposal is necessary (e.g. what inspired you to propose it, what particular problem you encountered). Having clear motivations helps us to judge whether there might be a better alternative way to approach the concerns. ::: Feature discussions are often lost or forgotten within chaotic group discussion forums or chatrooms. \ When plans or implementation ideas are discussed, some of these suggestions or ideas may be missed if not implemented immediately. There is also a concern that, even when all parties remember the discussion of a feature proposal, they may have reached different understandings about the outcome of said discussion: in other words, while we might agree about a conversation taking place, we might have different recollections of what was actually decided as a result of the conversation. The 'Skript Enhancement Proposals' format aims to mimic something similar to [Java's JEPs](https://openjdk.org/jeps/0). It gives the team a space to fully explain a feature and, if necessary, publish it as an information document. ## Description :::info A clear description of the proposal with all its details and features. ::: We aim to set a standard format for drafting proposals for large features or systemic changes that affect the organisation or our projects. There is no barrier to entry for these proposals: any member of the team can write one, and anybody can provide feedback on them. A proposal should be a simple and formulaic description of the idea, where it came from, and what it hopes to achieve, as well as a description of how it is expected to be implemented. During the development life cycle of the feature, its proposal can be revisited, redrafted, updated and tweaked as necessary. These proposals can be shipped or published easily, as announcements or warnings of an incoming change, or to encourage feedback and discussion from users and regular contributors. ### The Proposal Format Below is a standardised format for proposals, which can be copied and pasted into a new draft document. ```md #  ||| |-------:|:-------| |Creator || |Type || |Status || |Created || ## Summary ## Introduction ### Goals ### Non-Goals  ### Motivations ## Description ## Alternatives  ## Conclusion ### Addendum: Failure Standards ``` ## Alternatives :::info An __optional__ section. \ Here you can describe any alternative approaches to your proposal that you think are worth considering. ::: We could continue with the current model. We could use the GitHub Discussions area more extensively. ## Conclusion :::info Any final notes about the proposal. This is also a chance to explain how your idea achieves the goals you set out above. ::: We hope that by having a standardised and easy-to-follow format for proposals it will make future ideas easier to document. Having a set of required 'fill in the blanks' sections should reduce the chances of some important detail being missed from a proposal. Enforcing clear goals and failure standards should also make it easier to judge how successful an idea has been and whether we need to address it again in future. ### Addendum: Failure Standards :::info No proposal is complete without failure standards. You must list criteria for judging whether your proposal has failed and, if possible, a time-frame. Criteria for failure are important: if a project has failed we can work on reverting it, fixing it or creating an alternative idea that will perform better. A simple example would be: > This proposal will have failed if, within X months: > - Load time has not decreased by X > - The project has cost more than X > - User approval rating is below X ::: No proposal is complete without failure standards; the proposal system can be deemed to have failed if, in two years' time: 1. Important, systemic changes are not being properly explained or described. 2. The results of team planning and discussion are still being lost or forgotten. 3. The implementations of large features are deviating from the goals and design in their redrafted proposals. 4. The proposals system has been discarded in favour of a replacement.