diff --git a/source/guides/contributing/beginning.md b/source/guides/contributing/beginning.md new file mode 100644 index 0000000..7032e84 --- /dev/null +++ b/source/guides/contributing/beginning.md @@ -0,0 +1,41 @@ +How to Start Contributing to Denizen +--------------------------------- + +```eval_rst +.. contents:: Table of Contents + :local: +``` + +### Do you Need to Know Java? + +No! You can begin contributing to Denizen without any prior experience. You'll begin with simple contributions that will help you learn what you need for more advanced topics. You'll find that your experience with DenizenScript will help greatly in understanding Denizen's internals. + + +### What Do You Need to Start? + +#### Software + +To begin, you'll need software designed for Java development and Git, in order to bring Denizen to your own computer and submit changes. + +For the IDE(code editor), we strongly recommend [IntelliJ IDEA](https://www.jetbrains.com/idea/). This editor is specifically designed for Java projects and will handle dependencies on its own. +We suggest using GitHub Desktop, as it allows you to view and manage changes much more easily than the command-line tool. + +#### Spigot + +You must build Spigot on your computer before you can work with Denizen. To do this, download Spigot's [BuildTools](https://www.spigotmc.org/wiki/buildtools/). Once you have it, you will build each version listed in the [project README](https://github.com/DenizenScript/Denizen#readme) one at a time. You can use the tool's GUI, being sure to select `remapped` in the options menu prior, or you may use the command line with a command like `java -jar BuildTools.jar --rev 26.2 --remapped`. This will take a few minutes for each build. You don't need to keep the final jars outputted, though you may find them useful for your local test server; the building process creates files in your home directory the IDE will use later. + +### Getting your Project Set Up + +Once you have the requisite software, you'll need to get a copy of Denizen of your very own to make changes to! You'll need to make a `fork` of Denizen. It's generally easiest to do this on the GitHub website. You can find [Denizen's Repository](https://github.com/DenizenScript/Denizen) here to do so. From there, clone the repository to your computer. In GitHub Desktop, you can do this with the repository dropdown in the top left. This will copy all the files to your computer. You can then open the whole folder you just made with IntelliJ and browse the files. Don't worry if it's confusing right now! + +### What Do You Start With? + +Now that you have Denizen's file in front of you, you'll need to decide what you want to work on! If you don't have any prior experience working in Java, we suggest that you begin by adding or changing a tag, mechanism, or event. These components are designed to be easy to build on and there are lots of examples for you to look at or even copy as a starting place. The best place to start is in the Denizen Discord server's Denizen channel, where you can select the `Easy PR` tag to filter for posts that the helpers believe would be good for newer contributors! Once you have one in mind, you can use that thread to either mention that you'll be starting work on it, or to ask questions if you need. You may find [this page on properties](https://guide.denizenscript.com/guides/contributing/property-dev.html) useful if you're starting with a tag or mechanism. + +### Your First PR + +Once you know what you'll be doing, you need to create a new branch in your git repository. Name it something related to what you're working on, but the specific name doesn't matter. You're then set to start editing code. You'll find some of the other pages of this guide helpful for implementing and testing the change, but this page focuses on the process, so we'll assume that you've finished successfully and are ready to submit it for review. You need to commit and push your changes. Once you've done that, GitHub desktop or web make it easy to submit a pull request to the main Denizen repository. Make sure to name it descriptively with what you changed, and include a reference to the thread originally requesting it. It's nice to also make another comment in the original thread with a link to your new PR. + +### What to Expect Now + +After you submit your PR, it will appear for review by existing contributors. Depending on circumstance, this review could take anywhere from minutes to a few days. Most likely, you'll get one or more comments on your pull request. You can review these on GitHub and respond to them. We try to be extra thorough with newer contributors to help you learn good practices and improve your abilities, so don't be discouraged if it seems like you're getting a lot of feedback; we want to help! Also, don't take initial comments as law. If you disagree, feel free to share why you did it one way instead of another. Once you've resolved all the comments, your pull request can be merged and incorporated into Denizen. You'll likely get a mention later in the Discord and everyone will be able to use your change! You may get the ability to chat in the contribution channel as well, which you can use to discuss your PRs in the future or ask questions. diff --git a/source/guides/contributing/building.md b/source/guides/contributing/building.md index 7483308..c68f5ac 100644 --- a/source/guides/contributing/building.md +++ b/source/guides/contributing/building.md @@ -1,4 +1,4 @@ -Working With and Building Denizen +Building Denizen and Testing Changes --------------------------------- ```eval_rst @@ -6,23 +6,16 @@ Working With and Building Denizen :local: ``` -### Prerequisites - -Make sure you have the following tools installed on your machine: - -- Some form of git. We recommend [GitHub Desktop](https://desktop.github.com/) (if you're using Linux, don't worry, there's probably a package for your distro). -- [IntelliJ IDEA](https://www.jetbrains.com/idea/). This editor is specifically designed for Java projects and will handle dependencies on its own. - -### Building Spigot +### Building Denizen -To build Denizen, you'll also need to build the supported versions of Spigot, which you can find on the [project README](https://github.com/DenizenScript/Denizen#readme). To do this, Spigot provides a tool called [BuildTools](https://www.spigotmc.org/wiki/buildtools/). This cannot be substituted with prebuilt jars or forks, as it must be built into your local maven repo. +After you've made changes to Denizen's code, you'll need to test them thoroughly to ensure that they function as expected in all use-cases. To do this, you'll need to build the plugin, with your changes, into a custom .jar file. +The easiest way to do this is to use IntelliJ's Maven plugin's GUI. In IntelliJ, on the right side, you should see an `M` symbol. Click that and it'll open a menu that looks like this: -Follow the setup instructions and then run the BuildTools jar for each version supported by Denizen. This should be a command like `java -jar BuildTools.jar --rev 1.21.1 --remapped`. +![](images/maven_menu.png) -### Building Denizen +Right click on `denizen-parent` and select "Run Maven Build". This will take a few moments, especially the first time you do it. Wait until the console tells you that the build is sucessful, and then navigate to your repository. In the root directory, you'll find /target, and the` .jar` will be inside. This is your plugin and you can put it into your [test server](/guides/first-steps/local-test-server) and try it! Make sure you get the jar from the target directory in the root. -1. Clone the Denizen repository: https://github.com/DenizenScript/Denizen -2. Open the cloned folder with IntelliJ. -3. Open the Maven tab, select `denizen-parent`, and click "Run Maven Build" (the green arrow). +### Testing Changes -After building, the jar will be available in the `target` folder. You can stick this into your test server's plugins folder and all of Denizen should be available. You can repeat step 3 to build the project after making any desired changes. +How you test changes varies greatly depending on the nature of the feature, but you'll want to make sure that it works when used correctly and gracefully errors when used incorrectly on each version that it supports. Unless you've set otherwise, this means that you need to test it on each minecraft version that Denizen supports. +You should try to think a little outside-the-box when testing for failures, as you may be surprised just how incorrectly users manage to use your feature. For example, if you're adding a tag, command, or mechanism, try giving no input, input of the completely wrong object type, empty input, misordered input, or so on. If your change uses a location, try it on locations that are unloaded, do not exist at all (such as in a made-up world name), with noted locations. It's not possible or expected to catch every possible mistake, and Denizen will often handle user-created problems for you before your code ever runs, but do your best! diff --git a/source/guides/contributing/images/maven_menu.png b/source/guides/contributing/images/maven_menu.png new file mode 100644 index 0000000..8a84e7d Binary files /dev/null and b/source/guides/contributing/images/maven_menu.png differ diff --git a/source/guides/contributing/layout.md b/source/guides/contributing/layout.md index 5e6a588..2f4d710 100644 --- a/source/guides/contributing/layout.md +++ b/source/guides/contributing/layout.md @@ -12,4 +12,21 @@ Any Denizen implementation depends on **DenizenCore**, which is the main set of Support for other plugins within Denizen scripts is provided by **Depenizen**. It uses the tools provided by both DenizenCore and Denizen to interact with external APIs. This is also the case for **dDiscordBot**, although it focuses on a single API (that being Discord). +### Repository Modules + +Denizen uses a multi-module Maven setup. The primary directories you will encounter in the repository are: + +- `plugin`: Contains the core logic, tags, commands, and script events. Most pull requests belong in `plugin/src/main/java/com/denizenscript/denizen/`. +- `paper`: Contains Paper-specific tags, events, and API features. +- Version modules formatted like `v1_20`: Contain version-specific NMS code for direct server internals. +- `dist`: Bundles all modules into the final compiled jar. + +### What to Contribute + +As a new contributor, you might wonder what kind of changes you should focus on. Adding, changing, improving, or fixing **tags, mechanisms, commands, and events** is considered the range of what anyone can contribute and is a great place to start and gain experience! This will help you learn the codebase and prepare you to tackle more advanced features later. You should avoid contributing to deep core functionality (like `DenizenCore`) until you are more familiar with the project. + +### Finding Existing Source Code + Unless you're going to be working with core language features, most of your code will be recognizably similar, and you can find numerous examples throughout these projects for each type of contribution. + +**Tip:** You can easily find existing source code using the [Meta Docs](https://meta.denizenscript.com). Searching for any tag or command on the site provides a direct source link at the bottom of the page, pointing to the exact Java class and line number in the repository.