Skip to content
This repository has been archived by the owner on Sep 2, 2024. It is now read-only.

Contributing: Getting Started

Jump to bottom
pomchom edited this page Mar 26, 2024 · 8 revisions

recode is an open-source mod, so anyone in the DiamondFire community is welcome (and encouraged!) to help with the project. The following few wiki pages intend to make it easier to get into contributing. They are written for the audience of people who already have experience coding in Java, but at times we will re-explain things just in case.

Preamble

Before starting to actually code, there are a few pieces of information you should be aware of, and a few guidelines you should follow. However, don't be intimidated or afraid to contribute! Even if you're a beginner, we're happy to help beyond what is explained on the wiki.

(Note that the wiki pages are also a work-in-progress and will be improved over time as feedback is gathered.)

TL;DR

  1. Post a suggestion or issue report before contributing.
  2. Write safe and clean code, preferring Kotlin to Java.
  3. Create one pull request per feature/fix and one branch per pull request.

Open-source Etiquette

Since many of you reading this perhaps have never contributed to an open-source project before, it is important to note that open-source does not mean that anyone can add anything they want to the mod. It still has a project lead (me, pomchom), a developer team who make decisions, etc. While contributing code to the project yourself can be a great way to help features get added (and added the way you want them to be added), you don't want to simply contribute everything and anything at your discretion, as that just makes things harder for everyone, yourself included.

The Contribution Process

The general process for contributing is as follows:

  1. Find something you want to add or fix, if you don't have one already. Our Discord, the Issues tab on GitHub, and the roadmap are all good places to look.
  2. If it's anything more than a very minor addition or simple bugfix, start by finding or creating a suggestion or issue report (don't create one if it already exists!). This can be done on our Discord or via the Issues tab. If there is anything you need to know before proceeding, a developer and/or contributor will tell you there.
  3. If you don't have one already, create a fork of the repository to make your code changes on, then create a new branch to make your changes on. If you are not comfortable with using Git or GitHub, see below.
  4. Once ready, submit your changes for approval by creating a pull request (PR). Developers and contributors may comment on your PR requesting changes.

Working with Tools

The following are things you should keep in mind, but are not strictly related to recode.

Safety and Convention

Writing safe and clean code is important to ensure that the code you write is (mostly) bug-free, doesn't cause unintended effects, and can be easily read and changed by others. By "safe" code I mean code that follows statically typed coding practices, and by "clean" code I mean code that follows Java and Kotlin coding conventions within reason and isn't over-complicated or over-engineered.

  1. Avoid reliance on runtime errors as much as possible, as those lead to crashes. Prefer static typing and compile errors, but when necessary, try/catch your code properly. Don't just catch all exceptions and print the stack trace.
  2. Write abstract and polymorphic code when appropriate. Prefer interfaces to open inheritance (sealed classes and private open classes are fine).
  3. Don't work with threads directly. In simple cases use the Power class provided by recode, which works in tandem with the kotlinx.coroutines library. In more complicated cases you may use CoroutineScope. Note that this is a pretty complicated library, as asynchronous code is hard to write safely in general, so if you don't feel comfortable with this, let someone else do it instead.

Kotlin

As the mod is gradually migrating to Kotlin, prefer writing Kotlin over Java for new files. When modifying old files written in Java, you can of course keep them in Java. If you do not know the Kotlin language, you will want to familiarize yourself by reading its documentation. (Don't worry - the basics are extremely simple if you know Java! You'll be glad you learned it.) Note that mixins are still written exclusively in Java.

You will want to especially be familiar with the following concepts, as recode uses them extensively:

  1. Extensions
  2. Kotlin lambdas and inline functions
  3. sealed, data, and object
  4. The by keyword
  5. Scope functions

Git

Git is what we use to track and manage changes to the code by different people. This page is not a Git tutorial, but because it is so easy to mess up while using, and fixing issues with Git can be a massive pain, I wanted to put some basic tips here and address some common pitfalls.

  1. Create one pull request per feature or fix. We don't want unrelated changes in the same pull request because that makes it much harder to approve, deny, or comment/request changes on individual features or groups of code. Changes/fixes can share a pull request if they are very related.
  2. Always create a new branch before starting something new. This is because pull requests are created from branches, not specific changes. If you create a pull request from a branch and then make new changes on that branch, those new changes are automatically applied to the pull request as well, and as mentioned above we don't want unrelated changes and fixes in the same pull request.
  3. Be careful with rebase. Git provides two options when combining your local changes and changes from a repository: merge and rebase. If there are no merge conflicts, meaning the two sets of changes can be safely combined without issue, then these two are the same. But when there are conflicts, it is important to be careful with rebase. If you are unsure, just stick to merge, but if you are going to rebase, ONLY do so if you have not pushed anything since. This is because rebase rewrites commit history to make your local changes the newest, rather than introducing additional merge commits. This leads to a cleaner Git tree but overwrites commit history, so using it with already public commits is an absolute no-no.

Next Steps

So far we have not discussed how to actually add features or make changes properly; the remaining wiki pages cover that and we recommend reading them in the order below. Topics include:

Again, don't be shy! We're happy to help on Discord and would appreciate feedback on how to improve these pages.

Clone this wiki locally