Skip to content

Latest commit

 

History

History
129 lines (93 loc) · 6.17 KB

CONTRIBUTING.md

File metadata and controls

129 lines (93 loc) · 6.17 KB

Contributing to Kapi

Last Updated: September 7th, 2024

Thank you so much for showing interest in contributing to Kapi! Here are a set of instructions and guidelines for contributing code or documentation to the project. This document will change over time, so make sure that your contributions still line up with the requirements here before submitting a pull request.

Important

By contributing to Kapi, you agree that your contributions will be licensed under the GNU General Public License 3.0. This ensures that all contributions remain free and open-source.

Getting Started

  • Check the Planned Features page, as well as the open Issues and Pull Requests.
  • If you'd like to add a feature that isn't on the roadmap or doesn't have an open issue, PLEASE create a feature request issue discussing your intentions, so any feedback or important information can be given by the team first.
    We don't want you to waste time developing a feature or making a change that can't/won't be added.

Contribution Checklist

  • I've read the Planned Features page.
  • I've checked the open Issues and Pull Requests.
  • I've created a new issue for my feature before starting to work on it, or have at least notified others in the relevant existing issue(s) of my intention to work on it.
  • I've set up my development environment (for code contributions).
  • I've read the Code Guidelines and/or Documentation Guidelines

Creating a Development Environment

Prerequisites

  • Java
  • JDK 17 (can be downloaded automatically if using IntelliJ)
  • Gradle (can be downloaded automatically if using IntelliJ)
  • IntelliJ (optional, highly recommended)

Clone the repo

Using IntelliJ

Go to file -> new -> Project from Version Control and click it.
Make sure "git" is selected and set the URL field to: https://github.com/KapiMC/kapi Click "Clone".

Using Git

Clone the repo by running:

$ git clone https://github.com/KapiMC/docs.git

Compiling and Testing using IntelliJ

  • Make sure IntelliJ has detected the Gradle project.
  • To compile, run the gradle build task, it's recommended to set this as your run configuration.
  • To test, run the gradle test task, it's recommended to set this as your run configuration.

If Gradle successfully compiled the project, the jar should be available at Kapi/build/libs/.

Manually Compiling and Testing (Outside an IDE)

  • Windows

    • To compile, run gradlew.bat build in command prompt or PowerShell.
    • To test, run gradlew.bat test in command prompt or PowerShell.

  • Linux/macOS

    • To compile, run gradlew build in your shell.
    • To test, run gradlew test in your shell.

If Gradle successfully compiled the project, the jar should be available at Kapi/build/libs/.

Code Guidelines

Style

Most of the style guidelines can be checked, fixed, and enforced via IntelliJ's Code Style Checker.
Go to Settings -> Editor -> Code Style, make sure "Scheme" is set to "Project".
Go to Settings -> Editor -> Inspections, make sure "Profile" is set to "Project Default".

  • Do your best to write clear, concise, and modular code.
  • Try to keep a maximum column width of no more than 100 characters, max is 120.
  • Code comments should be used to help describe sections of code that don't speak for themselves.
  • Add the @Kapi annotation for anything that is intended to be a part of the public API.
  • Use Javadoc to document any classes, methods, and enums you add.
  • Javadoc @param, @return and @throws should start with a lowercase letter, Javadoc descriptions should be English sentences starting with a capital letter.
  • If you're modifying an existing method that does not have a Javadoc, you don't have to add a Javadoc to it... but it would be pretty cool if you did ;)
  • Names (identifiers) should not contain multiple uppercase letters in a row (except for constants which should be SCREAMING_SNAKE_CASE), for example, Uuid not UUID, encryptRsaKey not encrpyRSAKey.
  • If something wasn't mentioned above and not enforced by IntelliJ, stick to Java's conventions and best practices.

Code Quality

  • Avoid nested if statements as much as possible.
  • Use Log instead of System.out.println() statements.
  • Prefer using Option and Result over null and exceptions.
  • Limit visibility of classes, methods, fields, and variables to the minimum necessary.
  • Prefer composition over inheritance, only use inheritance when needed, and prefer interfaces over abstract classes.
  • Use design patterns appropriately, don't overuse or misuse them.
  • Write tests for your code, or alternatively a Minecraft plugin using the code, to verify it works in-game.

Git/GitHub Specifics

  • Use clear and concise commit messages. If your commit does too much, either consider breaking it up into smaller commits or providing extra detail in the commit description.
  • Follow Conventional Commits, use past tense where it makes sense.
  • Pull Requests should have an adequate title and description which clearly outline your intentions and changes/additions. Feel free to provide screenshots, GIFs, or videos, especially for visual changes.

Documentation Guidelines

Documentation contributions are contributions to Kapi's Docs Website

  • Use kebab-case for file names
  • Follow the existing directory structure
  • Provide alt text for all embedded media
  • Use Title Case for Markdown headers