breaking things

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,27 +7,61 @@ assignees: ''
 
 ---
 
+### Read me before you open an issue! ###
+
+#### Instructions
+
+This is a template for the issue you are about to open! It will help you provide the information necessary
+to complete your **bug report**. Before you open an issue, ensure you've completed every step on the checklist below.
+
+- Have you used the search tool to find similar issues? Make sure you are not opening a duplicate.
+- Are you using the latest version of the mod? If not, try updating to see if it resolves your issue.
+
+All good? Please read through the sections below, and fill out any lines starting with an arrow. Then, remove
+everything above this dashed line (including the line itself.)
+
+------------------------
+
+### Version Information
+
+> Replace this text with the exact version of the mod you are using. Every part of the version is important! If you
+> do not know what version you are using, look at the file name in your "mods" folder.
+> 
+> Example: mc1.16.4-0.1.1+rev.4b3964a
+
 ### Expected Behavior
-Replace this text with what you expected to happen.
-_Example: The Piston should extend._
+
+> Replace this text with what you expected to happen.
+>
+> Example: The Piston should extend.
 
 ### Actual Behavior
-Replace this text with what actually happened.
-_Example: The Piston does not extend._
 
-### Reproduction Steps
-Provide information on how to reproduce this game crash. You can either fill in the example below or do something else -- just make sure your instructions are minimal and clear! If applicable, please provide a world file as a compressed ZIP which contains a minimally reproducible example of the issue. 
+> Replace this text with what actually happened.
+>
+> Example: The Piston does not extend.
 
-1. Place a Redstone Lamp beside a Redstone Repeater
-2. Use a Lever to activate the Redstone Repeater
-3. Nothing happens
+### Reproduction Steps
 
-### Attachments
-Add any relevant screenshots or videos to this issue as you feel necessary to explain the issue.
+> Provide information on how to reproduce this game crash. You can either fill this section in like the example below
+> or do something else -- just make sure your instructions are minimal and clear, as other people will need to be able
+> to replicate your issue.
+> 
+> Example:
+> 1. Place a Redstone Lamp in front of a Redstone Repeater
+> 2. Use a Lever to activate the Redstone Repeater
+> 3. Nothing happens
 
 ### System Information
-You can obtain this information from the in-game debug screen or through using [DxDiag](https://support.microsoft.com/en-us/help/4028644/windows-open-and-run-dxdiagexe) on Windows.
 
-- Java Version: [fill me in]
-- CPU: [fill me in]
-- GPU: [fill me in]
+> You can obtain this information from the right-side of the in-game debug screen (F3) or through using DxDiag
+> (https://support.microsoft.com/en-us/help/4028644/windows-open-and-run-dxdiagexe) on Windows. 
+> 
+> - Java Version: [fill me in]
+> - CPU: [fill me in]
+> - GPU: [fill me in]
+
+### Other Information
+
+> Provide a list of any other mods you are using, along with their respective versions. If you have any screenshots,
+> videos, or other information that you feel is necessary to explain the issue, feel free to attach them here.

.github/ISSUE_TEMPLATE/crash-report.md

@@ -7,15 +7,49 @@ assignees: ''
 
 ---
 
+### Read me before you open an issue! ###
+
+#### Instructions
+
+This is a template for the issue you are about to open! It will help you provide the information necessary
+to complete your **crash report**. Before you open an issue, ensure you've completed every step on the checklist below.
+
+- Have you used the search tool to find similar issues? Make sure you are not opening a duplicate.
+- Are you using the latest version of the mod? If not, try updating to see if it resolves your issue.
+
+All good? Please read through the sections below, and fill out any lines starting with an arrow. Then, remove
+everything above this dashed line (including the line itself.)
+
+------------------------
+
+### Version
+
+> Replace this text with the exact version of the mod you are using. Every part of the version is important! If you
+> do not know what version you are using, look at the file name in your "mods" folder.
+>
+> Example: mc1.16.4-0.1.1+rev.4b3964a
+> 
 ### Reproduction Steps
-Provide information on how to reproduce this game crash. This step is critical for ensuring that your crash can be debugged by other developers. You can either fill in the example below or do something else -- just make sure your instructions are minimal and clear. If applicable, provide a Minecraft save containing a minimal example on how to reproduce this crash as a compressed ZIP file.
 
-1. Place a Redstone Lamp beside a Redstone Repeater
-2. Use a Lever to activate the Redstone Repeater
-3. The game crashes
+> Provide information on how to reproduce this game crash. You can either fill this section in like the example below
+> or do something else -- just make sure your instructions are minimal and clear, as other people will need to be able
+> to replicate your issue.
+>
+> Example:
+> 1. Place a Redstone Lamp in front of a Redstone Repeater
+> 2. Use a Lever to activate the Redstone Repeater
+> 3. Nothing happens
 
 ### Crash Report File
-Please upload your crash report as a file to [GitHub Gist](https://gist.github.com/) and replace this text with a link to the uploaded report.
+
+> Upload your crash report file as an attachment to this issue (drag-and-drop) or to a service such as GitHub
+> Gist (paste a link) and replace this section. This information is critical in resolving your issue!
+> 
+> Tip: Messages like "Exit code 0" from your launcher are not what you're looking for. If your launcher does not
+> provide a button to view the most recent crash report, check your game's "crash-reports" folder for the most recent
+> crash report file.
 
 ### Additional Information
-Provide any additional information or context which may be relevant to the issue. If you have none to add, you can remove this section.
+
+> Provide any additional information or context which may be relevant to the issue. If you have none to add,
+> you can remove this section.

.github/workflows/gradle.yml

@@ -1,4 +1,4 @@
-name: Java CI with Gradle
+name: gradle-ci
 
 on: [ push, pull_request ]
 
@@ -12,7 +12,7 @@ jobs:
       uses: actions/setup-java@v1
       with:
         java-version: 8
-    - name: Build with Gradle
+    - name: Build artifacts
       run: ./gradlew build
     - name: Upload build artifacts
       uses: actions/upload-artifact@v1

.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Publish Release
+name: release-artifacts
 
 on:
   release:
@@ -15,10 +15,8 @@ jobs:
         uses: actions/setup-java@v1
         with:
           java-version: 8
-      - name: Upload assets to CurseForge
+      - name: Build artifacts
         run: ./gradlew build
-        env:
-          BUILD_RELEASE: ${{ github.event.prerelease == false }}
       - name: Upload assets to GitHub
         uses: AButler/[email protected]
         with:

README.md

@@ -1,70 +1,128 @@
 ![Project icon](https://git-assets.jellysquid.me/hotlink-ok/sodium/icon-rounded-128px.png)
 
 # Sodium (for Fabric)
-![GitHub license](https://img.shields.io/github/license/jellysquid3/sodium-fabric.svg)
-![GitHub issues](https://img.shields.io/github/issues/jellysquid3/sodium-fabric.svg)
-![GitHub tag](https://img.shields.io/github/tag/jellysquid3/sodium-fabric.svg)
-[![Discord chat](https://img.shields.io/badge/chat%20on-discord-7289DA)](https://jellysquid.me/discord)
-[![CurseForge downloads](http://cf.way2muchnoise.eu/full_394468_downloads.svg)](https://www.curseforge.com/minecraft/mc-mods/sodium)
+![GitHub license](https://img.shields.io/github/license/CaffeineMC/sodium-fabric.svg)
+![GitHub issues](https://img.shields.io/github/issues/CaffeineMC/sodium-fabric.svg)
+![GitHub tag](https://img.shields.io/github/tag/CaffeineMC/sodium-fabric.svg)
 
 Sodium is a free and open-source optimization mod for the Minecraft client that improves frame rates, reduces
 micro-stutter, and fixes graphical issues in Minecraft. 
 
 :warning: Sodium has had a lot of time to shape up lately, but the mod is still alpha software. You may run into small
 graphical issues or crashes while using it. Additionally, the
 [Fabric Rendering API](https://fabricmc.net/wiki/documentation:rendering) is not yet supported, which may cause crashes
-or prevent other mods from rendering correctly. Please be aware of these issues before using it in your game.
+and other issues with a number of mods.
 
-### Downloads
+---
 
-You can find downloads for Sodium on either the [official CurseForge page](https://www.curseforge.com/minecraft/mc-mods/sodium)
-or through the [GitHub releases page](https://github.com/jellysquid3/sodium-fabric/releases). Usually, builds will be
-made available on GitHub slightly sooner than other locations.
+## Installation
 
-### Community
+### Manual installation (recommended)
+
+You will need Fabric Loader 0.10.x or newer installed in your game in order to load Sodium. If you haven't installed
+Fabric mods before, you can find a variety of community guides for doing so [here](https://fabricmc.net/wiki/install).
+
+#### Stable releases
+
+![GitHub release](https://img.shields.io/github/release/CaffeineMC/sodium-fabric.svg)
+
+The latest releases of Sodium are published to our [Modrinth](https://modrinth.com/mods/sodium) and
+[GitHub release](https://github.com/CaffeineMC/sodium-fabric/releases) pages. Releases are considered by our team to be
+**suitable for general use**, but they are not guaranteed to be free of bugs and other issues.
+
+Usually, releases will be made available on GitHub slightly sooner than other locations.
+
+#### Bleeding-edge builds (unstable)
+
+[![GitHub build status](https://img.shields.io/github/workflow/status/CaffeineMC/sodium-fabric/gradle-ci/1.16.x/dev)](https://github.com/CaffeineMC/sodium-fabric/actions/workflows/gradle.yml)
+
+If you are a player who is looking to get your hands on the latest **bleeding-edge changes for testing**, consider
+taking a look at the automated builds produced through our [GitHub Actions workflow](https://github.com/CaffeineMC/sodium-fabric/actions/workflows/gradle.yml?query=event%3Apush).
+This workflow automatically runs every time a change is pushed to the repository, and as such, the builds it produces
+will generally reflect the latest snapshot of development.
 
-If you'd like to get help with the mod, check out the latest developments, or be notified when there's a new release,
-the Discord community might be for you! You can join the official server for my mods by clicking
-[here](https://jellysquid.me/discord).
+Bleeding edge builds will often include unfinished code that hasn't been extensively tested. That code may introduce
+incomplete features, bugs, crashes, and all other kinds of weird issues. You **should not use these bleeding edge builds**
+unless you know what you are doing and are comfortable with software debugging. If you report issues using these builds,
+we will expect that this is the case. Caveat emptor.
 
-### Building from source
+### CurseForge
+
+[![CurseForge downloads](http://cf.way2muchnoise.eu/full_394468_downloads.svg)](https://www.curseforge.com/minecraft/mc-mods/sodium)
+
+If you are using the CurseForge client, you can continue to find downloads through our
+[CurseForge page](https://www.curseforge.com/minecraft/mc-mods/sodium). Unless you are using the CurseForge
+client, you should prefer the downloads linked on our Modrinth or GitHub release pages above.
+
+The CurseForge client does not natively support Fabric modding, so you will need to install
+[Jumploader](https://www.curseforge.com/minecraft/mc-mods/jumploader) in order to set up your Fabric environment. Due to
+the extra complexity and startup overhead this workaround adds, we generally do not recommend using this method unless
+you have an existing setup with it.
+
+---
+
+### Reporting Issues
+
+You can report bugs and crashes by opening an issue on our [issue tracker](https://github.com/CaffeineMC/sodium-fabric/issues).
+Before opening a new issue, use the search tool to make sure that your issue has not already been reported and ensure
+that you have completely filled out the issue template. Issues which are duplicates or do not contain the necessary
+information to triage and debug may be closed. 
+
+Please note that while the issue tracker is open to feature requests, development is primarily focused on
+improving hardware compatibility, performance, and finishing any unimplemented features necessary for parity with
+the vanilla renderer.
+
+### Community
+[![Discord chat](https://img.shields.io/badge/chat%20on-discord-7289DA?logo=discord&logoColor=white)](https://jellysquid.me/discord)
 
-If you're hacking on the code or would like to compile a custom build of Sodium from the latest sources, you'll want
-to start here.
+We have an [official Discord community](https://jellysquid.me/discord) for all of our projects. By joining, you can:
+- Get installation help and technical support with all of our mods 
+- Be notified of the latest developments as they happen
+- Get involved and collaborate with the rest of our team
+- ... and just hang out with the rest of our community.
 
-#### Prerequisites
+---
 
-You will need to install JDK 8 (or newer, see below) in order to build Sodium. You can either install this through
-a package manager such as [Chocolatey](https://chocolatey.org/) on Windows or [SDKMAN!](https://sdkman.io/) on other
-platforms. If you'd prefer to not use a package manager, you can always grab the installers or packages directly from
-[AdoptOpenJDK](https://adoptopenjdk.net/).
+### Building from sources
 
-On Windows, the Oracle JDK/JRE builds should be avoided where possible due to their poor quality. Always prefer using
-the open-source builds from AdoptOpenJDK when possible.
+Support is not provided for setting up build environments or compiling the mod. We ask that
+users who are looking to get their hands dirty with the code have a basic understanding of compiling Java/Gradle
+projects. The basic overview is provided here for those familiar.
 
-#### Compiling
+#### Requirements
 
-Navigate to the directory you've cloned this repository and launch a build with Gradle using `gradlew build` (Windows)
-or `./gradlew build` (macOS/Linux). If you are not using the Gradle wrapper, simply replace `gradlew` with `gradle`
-or the path to it.
+- JRE 8 or newer (for running Gradle)
+- JDK 8 (optional)
+  - If you neither have JDK 8 available on your shell's path or installed through a supported package manager (such as
+[SDKMAN](https://sdkman.io)), Gradle will automatically download a suitable toolchain from the [AdoptOpenJDK project](https://adoptopenjdk.net/)
+and use it to compile the project. For more information on what package managers are supported and how you can
+customize this behavior on a system-wide level, please see [Gradle's Toolchain user guide](https://docs.gradle.org/current/userguide/toolchains.html).
+- Gradle 6.7 or newer (optional)
+  - The [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html#sec:using_wrapper) is provided in
+    this repository can be used instead of installing a suitable version of Gradle yourself. However, if you are building
+    many projects, you may prefer to install it yourself through a suitable package manager as to save disk space and to
+    avoid many different Gradle daemons sitting around in memory.
 
-The initial setup may take a few minutes. After Gradle has finished building everything, you can find the resulting
-artifacts in `build/libs`.
+#### Building with Gradle
 
-### Tuning for optimal performance
+Sodium uses a typical Gradle project structure and can be built by simply running the default `build` task. After Gradle
+finishes building the project, you can find the build artifacts (typical mod binaries, and their sources) in
+`build/libs`.
 
-_This section is entirely optional and is only aimed at users who are interested in squeezing out every drop from their
-game. Sodium will work without issue in the default configuration of almost all launchers._
+**Tip:** If this is a one-off build, and you would prefer the Gradle daemon does not stick around in memory afterwards,
+try adding the [`--no-daemon` flag](https://docs.gradle.org/current/userguide/gradle_daemon.html#sec:disabling_the_daemon)
+to ensure that the daemon is torn down after the build is complete. However, subsequent builds of the project will
+[start more slowly](https://docs.gradle.org/current/userguide/gradle_daemon.html#sec:why_the_daemon) if the Gradle
+daemon is not available to be re-used.
 
-Generally speaking, newer versions of Java will provide better performance not only when playing Minecraft, but when
-using Sodium as well. The default configuration your game launcher provides will usually be some old version of Java 8
-that has been selected to maximize hardware compatibility instead of performance.
 
-For most users, these compatibility issues are not relevant, and it should be relatively easy to upgrade the game's Java
-runtime and apply the required patches. For more information on upgrading and tuning the Java runtime, see the
-guide [here](https://gist.github.com/jellysquid3/8a7b21e57f47f5711eb5697e282e502e).
+Build artifacts ending in `dev` are outputs containing the sources and compiled classes
+before they are remapped into stable intermediary names. If you are working in a developer environment and would
+like to add the mod to your game, you should prefer to use the `modRuntime` or `modCompile` configurations provided by
+Loom instead of these outputs.
 
+---
 ### License
 
 Sodium is licensed under GNU LGPLv3, a free and open-source license. For more information, please see the
-[license file](https://github.com/jellysquid3/sodium-fabric/blob/1.16.x/dev/LICENSE.txt).
+[license file](https://github.com/CaffeineMC/sodium-fabric/blob/1.16.x/dev/LICENSE.txt).