From 508e008ed392962e136d4834786067493f30b1e0 Mon Sep 17 00:00:00 2001 From: sovdee <10354869+sovdeeth@users.noreply.github.com> Date: Fri, 21 Nov 2025 23:16:44 -0800 Subject: [PATCH 1/2] Improve contributing guide, add AI disclosure requirement. Remove Eclipse info from README --- .github/contributing.md | 178 +++++++++++++++++++++++-------- .github/pull_request_template.md | 1 + README.md | 15 --- 3 files changed, 133 insertions(+), 61 deletions(-) diff --git a/.github/contributing.md b/.github/contributing.md index 42ff9329706..37a8c18c7c1 100644 --- a/.github/contributing.md +++ b/.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 +[Git documentation](https://git-scm.com/learn). +``` +git clone https://github.com/SkriptLang/Skript +``` + +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 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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e1d56acf6c5..875c69fbaf9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -17,3 +17,4 @@ --- **Completes:** none **Related:** none +**AI assistance:** none diff --git a/README.md b/README.md index 7888a6e692e..e0a786e1096 100644 --- a/README.md +++ b/README.md @@ -84,21 +84,6 @@ That is, it runs skriptTestJava17, and skriptTestJava21. By running the tests, you agree to Mojang's End User License Agreement. -### Importing to Eclipse -With new Eclipse versions, there is integrated Gradle support, and it actually works now. -So, first get latest Eclipse, then import Skript as any Gradle project. Just -make sure to **keep** the configuration when the importer asks for that! - -If you encounter strange issues, make sure you follow the instructions above and have -actually downloaded latest Eclipse or update your installation correctly. Skript's -new Gradle version (starting from dev26) does not work very well with older Eclipse -versions. Also, do *not* use Gradle STS; it is outdated. - -### Importing to IDEA -You'll need to make sure that nullness annotations are working correctly. Also, -when sending pull requests, make sure not to change IDEA configuration files -that may have been stored in the repository. - ### Releasing ``` ./gradlew clean build From e643d05bdae02b6477ff8c23b4090588b19df7d0 Mon Sep 17 00:00:00 2001 From: sovdee <10354869+sovdeeth@users.noreply.github.com> Date: Sat, 22 Nov 2025 17:38:01 -0800 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Eren <67760502+erenkarakal@users.noreply.github.com> --- .github/contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/contributing.md b/.github/contributing.md index 37a8c18c7c1..62c4bb61b31 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -77,7 +77,7 @@ project! ### 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 +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 @@ -92,7 +92,7 @@ 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 or Eclipse. +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