# Contributing to CC: Tweaked As with many open source projects, CC: Tweaked thrives on contributions from other people! This document (hopefully) provides an introduction as to how to get started with helping out. If you've any other questions, [just ask the community][community] or [open an issue][new-issue]. ## Table of Contents - [Reporting issues](#reporting-issues) - [Translations](#translations) - [Setting up a development environment](#setting-up-a-development-environment) - [Developing CC: Tweaked](#developing-cc-tweaked) - [Writing documentation](#writing-documentation) ## Reporting issues If you have a bug, suggestion, or other feedback, the best thing to do is [file an issue][new-issue]. When doing so, do use the issue templates - they provide a useful hint on what information to provide. ## Translations Translations are managed through [Weblate], an online interface for managing language strings. This is synced automatically with GitHub, so please don't submit PRs adding/changing translations! ## Setting up a development environment In order to develop CC: Tweaked, you'll need to download the source code and then run it. - Make sure you've got the following software installed: - Java Development Kit (JDK) installed. This can be downloaded from [Adoptium]. - [Git](https://git-scm.com/). - If you want to work on documentation, [NodeJS][node]. - Download CC: Tweaked's source code: ``` git clone https://github.com/cc-tweaked/CC-Tweaked.git cd CC-Tweaked ``` - Build CC: Tweaked with `./gradlew build`. This will be very slow the first time it runs, as it needs to download a lot of dependencies (and decompile Minecraft several times). Subsequent runs should be much faster! - You're now ready to start developing CC: Tweaked. Running `./gradlew :forge:runClient` or `./gradle :fabric:runClient` will start Minecraft under Forge and Fabric respectively. If you want to run CC:T in a normal Minecraft instance, run `./gradlew assemble` and copy the `.jar` from `projects/forge/build/libs` (for Forge) or `projects/fabric/build/libs` (for Fabric). ## Developing CC: Tweaked Before making any major changes to CC: Tweaked, I'd recommend you have a read of the [the architecture document][architecture] first. While it's not a comprehensive document, it gives a good hint of where you should start looking to make your changes. As always, if you're not sure, [do ask the community][community]! ### Testing When making larger changes, it may be useful to write a test to make sure your code works as expected. CC: Tweaked has several test suites, each designed to test something different: - In order to test CraftOS and its builtin APIs, we have a test suite written in Lua located at `projects/core/src/test/resources/test-rom/`. These don't rely on any Minecraft code, which means they can run on emulators, acting as a sort of compliance test. These tests are written using a test system called "mcfly", heavily inspired by [busted]. Groups of tests go inside `describe` blocks, and a single test goes inside `it`. Assertions are generally written using `expect` (inspired by Hamcrest and the like). For instance, `expect(foo):eq("bar")` asserts that your variable `foo` is equal to the expected value `"bar"`. These tests can be run with `./gradlew :core:test`. - In-game functionality, such as the behaviour of blocks and items, is tested using [Minecraft's gametest system][mc-test] (`projects/common/src/testMod`). These tests spin up a server, spawn a structure for each test, and then run some code on the blocks defined in that structure. These tests can be run with `./gradlew runGametest` (or `./gradle :forge:runGametest`/`./gradlew :fabric:runGametest` for a single loader). For more information, [see the architecture document][architecture]. ## Writing documentation When writing documentation for [CC: Tweaked's documentation website][docs], it may be useful to build the documentation and preview it yourself before submitting a PR. You'll first need to [set up a development environment as above](#setting-up-a-development-environment). Once this is set up, you can now run `./gradlew docWebsite`. This generates documentation from our Lua and Java code, writing the resulting HTML into `./projects/web/build/site`, which can then be opened in a browser. When iterating on documentation, you can instead run `./gradlew docWebsite -t`, which will rebuild documentation every time you change a file. Documentation is built using [illuaminate] which, while not currently documented (somewhat ironic), is largely the same as [ldoc][ldoc]. Documentation comments are written in Markdown, though note that we do not support many GitHub-specific markdown features. If you can, do check what the documentation looks like locally! When writing long-form documentation (such as the guides in [doc/guides](doc/guides)), I find it useful to tell a narrative. Think of what you want the user to learn or achieve, then start introducing a simple concept, and then talk about how you can build on that until you've covered everything! [new-issue]: https://github.com/cc-tweaked/CC-Tweaked/issues/new/choose "Create a new issue" [community]: README.md#community "Get in touch with the community." [Adoptium]: https://adoptium.net/temurin/releases?version=17 "Download OpenJDK 17" [checkstyle]: https://checkstyle.org/ [illuaminate]: https://github.com/SquidDev/illuaminate/ "Illuaminate on GitHub" [weblate]: https://i18n.tweaked.cc/projects/cc-tweaked/minecraft/ "CC: Tweaked weblate instance" [docs]: https://tweaked.cc/ "CC: Tweaked documentation" [ldoc]: http://stevedonovan.github.io/ldoc/ "ldoc, a Lua documentation generator." [mc-test]: https://www.youtube.com/watch?v=vXaWOJTCYNg [busted]: https://github.com/Olivine-Labs/busted "busted: Elegant Lua unit testing." [node]: https://nodejs.org/en/ "Node.js" [architecture]: projects/ARCHITECTURE.md