mirrors
/
CC-Tweaked
mirror of https://github.com/SquidDev-CC/CC-Tweaked
1
0
Fork 0
Code Issues Releases Wiki Activity
CC-Tweaked/CONTRIBUTING.md

105 lines
6.1 KiB
Markdown
Raw Permalink Normal View History

Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
# 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 in helping out.
If you've any other questions, [just ask the community][community] or [open an issue][new-issue].
## 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.
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
## 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!
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
## Developing
In order to develop CC: Tweaked, you'll need to download the source code and then run it. This is a pretty simple
Added Windows thing. (#500)
2020-07-18 17:59:52 +00:00
process. When building on Windows, Use `gradlew.bat` instead of `./gradlew`.
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
Move repo to cc-tweaked org Let's see how this goes. - Update references to the new repo - Use rrsync on the server, meaning make-doc.sh uploads relative to the website root. - Bump Gradle wrapper to 7.2. Not related to this change, but possibly fixes running under Java 16. Possibly.
2021-10-17 17:14:22 +00:00
- **Clone the repository:** `git clone https://github.com/cc-tweaked/CC-Tweaked.git && cd CC-Tweaked`
Merge branch 'master' into mc-1.14.x This also deletes display list support - MC 1.14 now requires VBOs to be supported in some capacity.
2020-04-22 08:45:23 +00:00
- **Setup Forge:** `./gradlew build`
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
- **Run Minecraft:** `./gradlew runClient` (or run the `GradleStart` class from your IDE).
Gitpod Support (#817)
2021-06-12 20:33:08 +00:00
- **Optionally:** For small PRs (especially those only touching Lua code), it may be easier to use GitPod, which
Move repo to cc-tweaked org Let's see how this goes. - Update references to the new repo - Use rrsync on the server, meaning make-doc.sh uploads relative to the website root. - Bump Gradle wrapper to 7.2. Not related to this change, but possibly fixes running under Java 16. Possibly.
2021-10-17 17:14:22 +00:00
provides a pre-configured environment: [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-2b2b2b?logo=gitpod)](https://gitpod.io/#https://github.com/cc-tweaked/CC-Tweaked/)
Gitpod Support (#817)
2021-06-12 20:33:08 +00:00
Do note you will need to download the mod after compiling to test.
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
If you want to run CC:T in a normal Minecraft instance, run `./gradlew build` and copy the `.jar` from `build/libs`.
These commands may take a few minutes to run the first time, as the environment is set up, but should be much faster
afterwards.
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
The following sections describe the more niche sections of CC: Tweaked's build system. Some bits of these are
quite-complex, and (dare I say) over-engineered, so you may wish to ignore them. Well tested/documented PRs are always
preferred (and I'd definitely recommend setting up the tooling if you're doing serious development work), but for
small changes it can be a lot.
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
### Code linters
CC: Tweaked uses a couple of "linters" on its source code, to enforce a consistent style across the project. While these
Bump Cobalt version - Remove stub for table.pack/table.unpack. - Remove Lua 5.3 bitlib stub. We're not on 5.3, there's no point emulating it. - Change peripheral.call to correctly adjust the error level. This is a terrible hack, but I believe the only good option. It'd be good to remove load as well, but it's a little more complex due to our injecting of _ENV. Closes #363
2020-04-16 09:48:26 +00:00
are run whenever you submit a PR, it's often useful to run this before committing.
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
- **[Checkstyle]:** Checks Java code to ensure it is consistently formatted. This can be run with `./gradlew build` or
`./gradle check`.
Use a Gradle plugin to download illuaminate Previously illumainate required manual users to manually download it and place it in ./bin/. This is both inconvenient for the user, and makes it hard to ensure people are running the "right" version. We now provide a small Gradle plugin which registers illuaminate as a ependency, downloading the appropriate (now versioned!) file. This also theoretically supports Macs, though I don't have access to one to test this. This enables the following changes: - The Lua lint script has been converted to a Gradle task (./gradle lintLua). - illuaminateDocs now uses a task definition with an explicit output directory. We can now consume this output as an input to another task, and get a task dependency implicitly. - Move the pre-commit config into the root of the tree. We can now use the default GitHub action to run our hooks. - Simplify CONTRIBUTING.md a little bit. Hopefully it's less intimidating now.
2022-09-11 13:11:32 +00:00
- **[illuaminate]:** Checks Lua code for semantic and styleistic issues. This can be run with `./gradlew lintLua`.
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
### 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.
Use a Gradle plugin to download illuaminate Previously illumainate required manual users to manually download it and place it in ./bin/. This is both inconvenient for the user, and makes it hard to ensure people are running the "right" version. We now provide a small Gradle plugin which registers illuaminate as a ependency, downloading the appropriate (now versioned!) file. This also theoretically supports Macs, though I don't have access to one to test this. This enables the following changes: - The Lua lint script has been converted to a Gradle task (./gradle lintLua). - illuaminateDocs now uses a task definition with an explicit output directory. We can now consume this output as an input to another task, and get a task dependency implicitly. - Move the pre-commit config into the root of the tree. We can now use the default GitHub action to run our hooks. - Simplify CONTRIBUTING.md a little bit. Hopefully it's less intimidating now.
2022-09-11 13:11:32 +00:00
Our documentation generation pipeline is rather complex, and involves invoking several external tools. Most of this
complexity is hidden by Gradle, but you will need to perform some initial setup:
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
Use a Gradle plugin to download illuaminate Previously illumainate required manual users to manually download it and place it in ./bin/. This is both inconvenient for the user, and makes it hard to ensure people are running the "right" version. We now provide a small Gradle plugin which registers illuaminate as a ependency, downloading the appropriate (now versioned!) file. This also theoretically supports Macs, though I don't have access to one to test this. This enables the following changes: - The Lua lint script has been converted to a Gradle task (./gradle lintLua). - illuaminateDocs now uses a task definition with an explicit output directory. We can now consume this output as an input to another task, and get a task dependency implicitly. - Move the pre-commit config into the root of the tree. We can now use the default GitHub action to run our hooks. - Simplify CONTRIBUTING.md a little bit. Hopefully it's less intimidating now.
2022-09-11 13:11:32 +00:00
- Install [Node/npm][node].
- Run `npm ci` to install our Node dependencies.
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
Use a Gradle plugin to download illuaminate Previously illumainate required manual users to manually download it and place it in ./bin/. This is both inconvenient for the user, and makes it hard to ensure people are running the "right" version. We now provide a small Gradle plugin which registers illuaminate as a ependency, downloading the appropriate (now versioned!) file. This also theoretically supports Macs, though I don't have access to one to test this. This enables the following changes: - The Lua lint script has been converted to a Gradle task (./gradle lintLua). - illuaminateDocs now uses a task definition with an explicit output directory. We can now consume this output as an input to another task, and get a task dependency implicitly. - Move the pre-commit config into the root of the tree. We can now use the default GitHub action to run our hooks. - Simplify CONTRIBUTING.md a little bit. Hopefully it's less intimidating now.
2022-09-11 13:11:32 +00:00
You can now run `./gradlew docWebsite`. This generates documentation from our Lua and Java code, writing the resulting
HTML into `./build/docs/site`.
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
#### Writing documentation
illuaminate's documentation system is not currently documented (somewhat ironic), but is _largely_ the same as
Add a pre commit hook to lint code This uses pre-commit [1] to check patches are well formed and run several linters on them. We currently do some boring things (check files are syntactically valid) as well as some project-specific ones: - Run illuaminate on the Lua files - Run checkstyle on Java [1]: https://pre-commit.com/
2021-04-28 20:24:27 +00:00
[ldoc][ldoc]. Documentation comments are written in Markdown,
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
Our markdown engine does _not_ support GitHub flavoured markdown, and so does not support all the features one might
Use a Gradle plugin to download illuaminate Previously illumainate required manual users to manually download it and place it in ./bin/. This is both inconvenient for the user, and makes it hard to ensure people are running the "right" version. We now provide a small Gradle plugin which registers illuaminate as a ependency, downloading the appropriate (now versioned!) file. This also theoretically supports Macs, though I don't have access to one to test this. This enables the following changes: - The Lua lint script has been converted to a Gradle task (./gradle lintLua). - illuaminateDocs now uses a task definition with an explicit output directory. We can now consume this output as an input to another task, and get a task dependency implicitly. - Move the pre-commit config into the root of the tree. We can now use the default GitHub action to run our hooks. - Simplify CONTRIBUTING.md a little bit. Hopefully it's less intimidating now.
2022-09-11 13:11:32 +00:00
expect. It is recommended that you build and preview the docs locally first.
When iterating on documentation, you can get Gradle to rebuild the website every time a file changes by running
`./gradlew docWebsite -t`. This will take a couple of seconds to run, but definitely beats running it manually!
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
### Testing
Thankfully running tests is much simpler than running the documentation generator! `./gradlew check` will run the
entire test suite (and some additional bits of verification).
Before we get into writing tests, it's worth mentioning the various test suites that CC: Tweaked has:
- "Core" Java (`./src/test/java`): These test core bits of the mod which don't require any Minecraft interaction.
This includes the `@LuaFunction` system, file system code, etc...
Add a pre commit hook to lint code This uses pre-commit [1] to check patches are well formed and run several linters on them. We currently do some boring things (check files are syntactically valid) as well as some project-specific ones: - Run illuaminate on the Lua files - Run checkstyle on Java [1]: https://pre-commit.com/
2021-04-28 20:24:27 +00:00
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
These tests are run by `./gradlew test`.
- CraftOS (`./src/test/resources/test-rom/`): These tests are written in Lua, and ensure the Lua environment, libraries
and programs work as expected. These are (generally) written to be able to be run on emulators too, to provide some
sort of compliance test.
Add a pre commit hook to lint code This uses pre-commit [1] to check patches are well formed and run several linters on them. We currently do some boring things (check files are syntactically valid) as well as some project-specific ones: - Run illuaminate on the Lua files - Run checkstyle on Java [1]: https://pre-commit.com/
2021-04-28 20:24:27 +00:00
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
These tests are run by the '"Core" Java' test suite, and so are also run with `./gradlew test`.
Use a Gradle plugin to download illuaminate Previously illumainate required manual users to manually download it and place it in ./bin/. This is both inconvenient for the user, and makes it hard to ensure people are running the "right" version. We now provide a small Gradle plugin which registers illuaminate as a ependency, downloading the appropriate (now versioned!) file. This also theoretically supports Macs, though I don't have access to one to test this. This enables the following changes: - The Lua lint script has been converted to a Gradle task (./gradle lintLua). - illuaminateDocs now uses a task definition with an explicit output directory. We can now consume this output as an input to another task, and get a task dependency implicitly. - Move the pre-commit config into the root of the tree. We can now use the default GitHub action to run our hooks. - Simplify CONTRIBUTING.md a little bit. Hopefully it's less intimidating now.
2022-09-11 13:11:32 +00:00
- In-game (`./src/testMod/java/dan200/computercraft/ingame/`): These tests are run on an actual Minecraft server, using
the same system Mojang do][mc-test]. The aim of these is to test in-game behaviour of blocks and peripherals.
Add a pre commit hook to lint code This uses pre-commit [1] to check patches are well formed and run several linters on them. We currently do some boring things (check files are syntactically valid) as well as some project-specific ones: - Run illuaminate on the Lua files - Run checkstyle on Java [1]: https://pre-commit.com/
2021-04-28 20:24:27 +00:00
Move some more build logic to buildSrc Look, I don't enjoy having 600 LOC long build.gradle files, it's just very easy to do! This at least moves some of the complexity elsewhere, so the build script is a little more declarative.
2022-10-22 19:47:47 +00:00
These tests are run with `./gradlew runGametest`.
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
## CraftOS tests
CraftOS's tests are written using a test system called "mcfly", heavily inspired by [busted] (and thus RSpec). 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"`.
Link to Weblate in CONTRIBUTING Let's make it at least a little bit discoverable!
2020-07-04 09:17:40 +00:00
Move repo to cc-tweaked org Let's see how this goes. - Update references to the new repo - Use rrsync on the server, meaning make-doc.sh uploads relative to the website root. - Bump Gradle wrapper to 7.2. Not related to this change, but possibly fixes running under Java 16. Possibly.
2021-10-17 17:14:22 +00:00
[new-issue]: https://github.com/cc-tweaked/CC-Tweaked/issues/new/choose "Create a new issue"
Add a separate CONTRIBUTING.md file Hopefully provides a /little/ more information about the build process. Hey, also means I only need to add a CoC to complete GH's community tab! In all seriousness, there's probably a lot more I need to flesh out here, such as some kind of vision and guides for issues/PRs. But this at least documents the local development process. Somewhat.
2020-04-13 09:54:57 +00:00
[community]: README.md#Community "Get in touch with the community."
[checkstyle]: https://checkstyle.org/
Expand CONTRIBUTING a little Explain our overly-complicated build system. Because of course we need to.
2021-01-15 23:16:58 +00:00
[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."
Use a Gradle plugin to download illuaminate Previously illumainate required manual users to manually download it and place it in ./bin/. This is both inconvenient for the user, and makes it hard to ensure people are running the "right" version. We now provide a small Gradle plugin which registers illuaminate as a ependency, downloading the appropriate (now versioned!) file. This also theoretically supports Macs, though I don't have access to one to test this. This enables the following changes: - The Lua lint script has been converted to a Gradle task (./gradle lintLua). - illuaminateDocs now uses a task definition with an explicit output directory. We can now consume this output as an input to another task, and get a task dependency implicitly. - Move the pre-commit config into the root of the tree. We can now use the default GitHub action to run our hooks. - Simplify CONTRIBUTING.md a little bit. Hopefully it's less intimidating now.
2022-09-11 13:11:32 +00:00
[node]: https://nodejs.org/en/ "Node.js"