Merge remote-tracking branch 'upstream/dev/feature' into cjh/event/FertilizeEgg

Author: CJH3139

.editorconfig

@@ -6,4 +6,8 @@ root = true
 end_of_line = lf
 indent_style = tab
 indent_size = 4
-charset = utf-8
+charset = utf-8
+
+[*.{yaml,yml}]
+indent_style = space
+indent_size = 2

.gitattributes

@@ -1,53 +1,51 @@
- # .gitattributes snippet to force users to use same line endings for project.
-        #
-        # Handle line endings automatically for files detected as text
-        # and leave all files detected as binary untouched.
-        * text eol=lf
+# Handle line endings automatically for files detected as text
+# and leave all files detected as binary untouched.
+* text eol=lf
 
-        #
-        # The above will handle all files NOT found below
-        # https://help.github.com/articles/dealing-with-line-endings/
-        # https://github.com/Danimoth/gitattributes/blob/master/Web.gitattributes
+# The above will handle all files NOT found below
+# https://help.github.com/articles/dealing-with-line-endings/
+# https://github.com/Danimoth/gitattributes/blob/master/Web.gitattributes
 
+# These files are text and should be normalized (Convert crlf => lf)
+*.php text
+*.css text
+*.js text
+*.json text
+*.htm text
+*.html text
+*.xml text
+*.txt text
+*.ini text
+*.inc text
+*.pl text
+*.rb text
+*.py text
+*.scm text
+*.sql text
+*.htaccess text
+*.sh text
+*.java text
 
+# These files are Windows-specific and should retain crlf
+*.bat text eol=crlf
 
-        # These files are text and should be normalized (Convert crlf => lf)
-        *.php text
-        *.css text
-        *.js text
-        *.json text
-        *.htm text
-        *.html text
-        *.xml text
-        *.txt text
-        *.ini text
-        *.inc text
-        *.pl text
-        *.rb text
-        *.py text
-        *.scm text
-        *.sql text
-        .htaccess text
-        *.sh text
-        *.java text
-
-        # These files are binary and should be left untouched
-        # (binary is a macro for -text -diff)
-        *.png binary
-        *.jpg binary
-        *.jpeg binary
-        *.gif binary
-        *.ico binary
-        *.mov binary
-        *.mp4 binary
-        *.mp3 binary
-        *.flv binary
-        *.fla binary
-        *.swf binary
-        *.gz binary
-        *.zip binary
-        *.7z binary
-        *.ttf binary
-        *.pyc binary
-	*.jar binary
-	*.class binary
+# These files are binary and should be left untouched
+# (binary is a macro for -text -diff)
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.mov binary
+*.mp4 binary
+*.mp3 binary
+*.flv binary
+*.fla binary
+*.swf binary
+*.gz binary
+*.zip binary
+*.7z binary
+*.ttf binary
+*.pyc binary
+*.jar binary
+*.class binary

.github/CODEOWNERS

@@ -70,3 +70,6 @@
 
 # EntityData
 /src/main/java/ch/njol/skript/entity @Absolutionism @skriptlang/core-developers
+
+# Particles/Effects
+/src/main/java/org/skriptlang/skript/bukkit/particles @sovdeeth @skriptlang/core-developers

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -7,8 +7,8 @@ body:
         ## Guidelines
         Please make sure you are running the latest version of Skript on a supported server platform and version.
         Try to make sure there are no issues of this same problem currently open either.
-        As of the release of Skript 2.13, the oldest supported version has been raised to Paper 1.20.4.
-        Any issues created for versions older than 1.20.4, or for Spigot, will not be looked into or fixed unless the issue persists on supported versions.
+        As of the release of Skript 2.14, the oldest supported version has been raised to Paper 1.21.0.
+        Any issues created for versions older than 1.21.0, or for Spigot, will not be looked into or fixed unless the issue persists on supported versions.
   - type: textarea
     attributes:
       label: Skript/Server Version

.github/contributing.md

@@ -26,72 +26,131 @@ Don't be scared to report real bugs, though. We won't be angry if we receive
 invalid reports; it is just that you're unlikely to get help with those here.
 
 ### Reporting Bugs
-So, you have found out a potential Skript bug. By reporting it correctly, you
-can ensure that it will be correctly categorized as a bug and hopefully, fixed.
 
-First, please make sure you have **latest** Skript version available. If there
-are no stable (no pre-release tag) versions, this means latest dev build.
-If you can find non-prerelease in downloads page of this repository, you may
-also use that one. Do **not** use 2.2, 2.1 or older, since while they are
-technically stable, they tend to not work reliably with Minecraft 1.9+.
+First, please make sure you have **latest** Skript version available. This means
+the latest stable (non-prerelease) version available under the releases page.
+If you are reporting a bug specific to a prerelease version, please make sure you
+are using the latest prerelease. If the bug is already fixed in latest version,
+please do not report it.
 
-Second, test without addons. No, seriously; unless you're an addon developer,
-test without plugins that hook to Skript before reporting anything. We can't
-help you with addon issues here, unless we get a lot of technical information
-about the addon in question. Issues that are not tested without addons are
-likely to be ignored by the core team.
+Second, test without addons. We won't help you with addon issues here.
+Issues that are not tested without addons are more likely to be ignored by the core team.
 
 If the issue still persists, search the issue tracker for similar
 errors and check if your issue might have been already reported.
-Only if you can't find anything, open a new issue.
+Only if you can't find anything, open a new issue. If you are unsure,
+open the issue anyway; we can always close it if needed.
 
 When opening an issue, pick a template for a bug report and fill it.
 We may ignore or close issues that are not made with correct templates.
+Please provide the full output of `/sk info` as requested in the template.
 
 ## Pull Requests
-Pull requests are a great way to contribute code, but there are still a few
-guidelines on how to use them.
 
-Note that these guidelines do not apply to pull requesting changes to
-documentation. For that kind of pull requests, just use common sense.
-
-### What to Contribute?
-You can find issues tagged with "help wanted" on tracker to see if there is
+### Pull Request Cheat Sheet
+A tl;dr version of the guidelines for contributing code:
+- Use the correct branch: `dev/feature` for new features or breaking changes, `dev/patch` for bug fixes and documentation changes.
+- Follow the code conventions. Disclose any AI assistance used.
+- Test your changes thoroughly, run the `quickTest` gradle task. Add more tests if possible.
+- Fill out the pull request template.
+- Respond to review comments in a timely and respectful manner.
+- Request re-reviews when you have addressed requested changes.
+- Feel free to politely ask for updates if your pull request has been open for a week or two without response.
+- Your contribution will be merged if it is ready prior to a release, so no need to worry.
+
+### Choosing What to Work On
+You can find issues tagged with "good first issue" on tracker to see if there is
 something for you. If you want to take over one of these, just leave a comment
 so other contributors don't accidentally pick same issue to work on. You can also
-offer your help to any other issue, but for "help wanted" tasks, help is really
-*needed*.
+offer your help to any other issue you want to work on!
 
-### Before Programming...
 If you did not pick an existing issue to work on, you should perhaps ask if your
-change is wanted. This can be done by opening an issue or contacting developer
-directly via Discord.
+change is wanted. Some changes may have already been considered and rejected, or
+may not fit into Skript's design goals. Opening an issue to discuss your idea is a good
+way to avoid wasted effort.
 
 Then, a few words of warning: Skript codebase will not be pleasant, easy or
 that sane to work around with. You will need some Java skills to create anything
 useful in sane amount of time. Skript is not a good programming/Java learning
 project!
 
-Still here? Good luck. If you did not learn how to use Git, now might be a good
-time to [learn](https://help.github.com/categories/bootcamp/).
+### Getting Started
+
+We welcome contributions from everyone. To get started, please fork the repository 
+and clone it to your local machine. If you are unfamiliar with Git, please refer to the
+[Git documentation](https://git-scm.com/learn).
+```
+git clone https://github.com/SkriptLang/Skript --recurse-submodules
+```
+
+Create a new branch for your changes. Use a descriptive name for the branch,
+such as `feature/your-feature-name` or `patch/fix-issue-number`. We request that 
+you base your changes on `dev/feature` branch for new features or breaking changes,
+ and `dev/patch` branch for bug fixes and documentation changes.
+```
+git checkout -b feature/your-feature-name dev/feature
+git checkout -b patch/fix-issue-number dev/patch
+```
+
+We recommend using an IDE such as IntelliJ (recommended) or Eclipse. 
+Please also make sure to follow our [code conventions](https://github.com/SkriptLang/Skript/blob/master/code-conventions.md).
+
+Building Skript requires Gradle. You can use the Gradle wrapper included in the
+repository to build Skript without installing Gradle globally.
+```
+./gradlew clean build
+```
+
+Finally, we request that you write descriptive commit messages that summarize the changes.
+We do not enforce any specific format or style for commit messages, but we ask that they
+generally consist of more than `Fix bug`, `Add feature`, or `Updated FileClass.java`.
+
+### AI assistance notice
+
+> [!IMPORTANT]
+>
+> If you are using **any kind of AI assistance** to contribute to Skript,
+> it must be disclosed in the pull request.
 
-### When Programming
-We recommend using an IDE; you can find some set up instructions in README.
-Please also follow our [code conventions](https://github.com/SkriptLang/Skript/blob/master/code-conventions.md).
+If you relied on AI assistance to make a pull request, you must disclose it in the
+pull request, together with the extent of the usage. For example, if you used
+AI to generate docs or tests, you must say it.
+An example disclosure:
+
+- > This PR was written primarily by Claude Code.
+- > I consulted ChatGPT to understand the codebase but the solution
+  > was fully authored manually by myself.
+
+Providing this information helps reviewers understand the context of the
+pull request and apply the right level of scrutiny, ensuring a smoother
+and more efficient review process.
+
+AI assistance isn't always perfect, even when used with the utmost care.
+
+Please be respectful to maintainers and disclose AI assistance. Failure to do so
+may lead to rejection of the pull request or removal of your ability to contribute
+to the repository.
 
 ### After Programming
 Test your changes. Actually, test more than your changes: if you think that you
 might have broken something unrelated, better to test that too. Nothing is more
-annoying than breaking existing features.
+annoying than breaking existing features. Please run the `quickTest` gradle task prior
+to submitting your changes to ensure that existing tests pass.
+```
+./gradlew clean quickTest
+```
 
-After manually testing, try to write some automated
+**After manually testing, try to write some automated
 [test scripts](https://github.com/SkriptLang/Skript/blob/master/src/test/skript/README.md)
-if possible. Remember that not everything can be tested this way, though.
+if possible**. Remember that not everything can be tested this way, though.
 
 When you are ready to submit a pull request, please follow the template. Don't
 be scared, usually everything goes well and your pull request will be present
 in next Skript release, whenever that happens.
 
+You should target the `dev/feature` branch for changes that add features or break existing functionality. \
+For bug fixes and documentation changes, target the `dev/patch` branch.
+
 Good luck!
 
 ### Submitting a Contribution
@@ -101,32 +160,59 @@ Having submitted your contribution it will enter a public review phase.
 Other contributors and users may make comments or ask questions about your contribution. \
 You are encouraged to respond to these - people may have valuable feedback!
 
-Developers may request changes to the content of your pull request. These are valuable since they may concern unreleased content. Please respect our team's wishes - changes are requested when we see room for improvement or necessary issues that need to be addressed.
+Developers may request changes to the content of your pull request. These are valuable 
+since they may concern unreleased content. Please respect our team's wishes - changes 
+are requested when we see room for improvement or necessary issues that need to be addressed.
 Change requests are not an indictment of your code quality.
 
-Developers may also request changes to the formatting of your code and attached files. These are important to help maintain the consistent standard and readability of our code base.
+Developers may also request changes to the formatting of your code and attached files. 
+These are important to help maintain the consistent standard and readability of our code base.
+
+**You must respond to these requests**. You can disagree, or propose alternatives, but you must
+engage in the discussion respectfully and in a timely manner. We will close pull requests
+that do not address requested changes within 6 months, though this is at our discretion, 
+and we may leave them open for more or less time depending on the situation. 
 
-Once you have made the requested changes (or if you require clarification or assistance) you can request a re-review from the developer.
+Once you have made the requested changes (or if you require clarification or assistance) 
+you can request a re-review from the developer. Please make sure to resolve any requested 
+changes you addressed.
 
-You don't need to keep your pull request fork up-to-date with Skript's master branch - we can update it automatically and notify you if there are any problems.
+You don't need to keep your pull request fork up-to-date with Skript's master branch - 
+we can update it automatically and notify you if there are any problems, but you must
+allow edits from maintainers on your pull request.
 
 ### Merging a Contribution
 
-Pull requests may be left un-merged until an appropriate time (e.g. before a suitable release.) This timeframe may be increased for breaking changes or significant new features, which might be better targeted in a major version.
+Pull requests may be left un-merged until an appropriate time (e.g. before a suitable release.) 
+We will try to merge contributions at a reasonable pace, but larger or more complex contributions
+may be left open for longer to allow for more thorough review.
 
-Please respect the process - this is a very complex project that takes a lot of time and care to maintain. Your contribution has not been forgotten about.
+All pull requests that are ready to be merged prior to a release will be included in that release, 
+so don't worry if your contribution is not merged immediately. If your pr has been open for a week 
+without a response, feel free to politely ask for an update. We may be busy, but we will get to it.
 
-For a contribution to be merged it requires at least two approving reviews from the core development team. It will then require a senior member to merge it.
+For a contribution to be merged it requires at least two approving reviews from the core development 
+team. It will then require a senior member to merge it.
 
-You do not need to 'bump' your contribution if it is un-merged; we may be waiting for a more suitable release to include it.
+You do not need to 'bump' your contribution if it is un-merged; we may be waiting for a more 
+suitable release to include it.
 
-If you have been waiting for a response to a question or change for a significant time please re-request our reviews or contact us.
+If you have been waiting for a response to a question or change for a significant time 
+please re-request our reviews or contact us. **Don't be shy about requesting reviews!** It's
+one of the easiest ways for us to see what needs our attention.
 
-In exceptional situations, pull requests may be merged regardless of review status by one of the organisation admins. 
+In exceptional situations, pull requests may be merged regardless of review status 
+by one of the organisation admins.
 
-### Peaceful Resolution
+## Peaceful Resolution
 
 Please respect our maintainers, developers, contributors and users. \
-Our contributors come from a wide variety of backgrounds and countries - you may need to explain issues and requests if they are misunderstood.
+Our contributors come from a wide variety of backgrounds and countries - 
+you may need to explain issues and requests if they are misunderstood.
+
+Please refer disrespectful and unpleasant behaviour to our tracker team. 
+For concerns about abuse, please contact the organisation directly.
 
-Please refer disrespectful and unpleasant behaviour to our tracker team. For concerns about abuse, please contact the organisation directly.
+## Acknowledgements
+We would like to acknowledge the [biomejs](https://github.com/biomejs/biome/blob/main/CONTRIBUTING.md#ai-assistance-notice) 
+team as the source and inspiration for our AI assistance notice.

.github/pull_request_template.md

@@ -17,3 +17,4 @@
 ---
 **Completes:** none <!-- Links to issues or discussions that should be completed when this PR is merged. -->
 **Related:** none <!-- Links to issues or discussions with related information -->
+**AI assistance:** none <!-- Was AI assistance used in the creation of this PR? If so, please specify the tool and extent of usage. -->