CONTRIBUTING.md

Contribution guidelines

Issues

• Before submitting a bug-related issue, make sure that its source is not the LibGDX itself.
• Feel free to create issues with feature requests and questions about the libraries. Issues are among the fastest way to contact the developers.

Pull requests

• The latest changes are always in the develop branch. master branch always matches the latest stable release. Make sure to checkout develop branch before starting your work and set develop as the target branch before creating a pull request.
• Include issue or pull request IDs in related commit messages. This makes it easier to locate more information about the changes. For example:

Kotlin version update. #250

• Format your code changes with the gradle format task. We are relying on automatic formatting performed with ktlint. Run gradle linterIdeSetup to apply formatter changes to your IntelliJ project.
• Follow our file naming convention:
  • Files with a single class: file name should match class name. E.g. FileLoader.kt.
  • Others: files with extension methods, top-level functions, utilities or multiple classes should use camel case nouns starting with a lower-cased letter. Should generally be in plural form. E.g. fileLoaders.kt.
• Make sure to include unit tests of your code. Test names should use the `backtick method name` syntax. JUnit and Spek can be used to write tests, although JUnit is encouraged for its commonness. Use Mockito-Kotlin for mocking.
• If your pull request is not a simple bug fix or small utility, make sure to link it to an existing issue or create an issue with your proposal first. Major API changes or new modules have to be discussed with the maintainers first. Skipping the issue will not get your pull request rejected outright, but note that undiscussed major changes might require a rewrite.
• All notable changes should be added to the changelog with an appropriate label:
  • [FEATURE] - a new functionality.
  • [CHANGE] - an API breaking change.
  • [UPDATE] - an update of one of the major dependencies.
  • [FIX] - a bug fix.
  • [MISC] - other changes (e.g. related to documentation or the project itself).
• Most libraries list all features in the README.md files to ease their usage. When adding a new feature, please check the README.md file of the module and add description of your change when appropriate. Any major feature should include a usage example in the module guide. Make sure to add all of the necessary imports in the usage examples in README.md files to make it easier to try them out.

Working from sources

git clone https://github.com/libktx/ktx.git
cd ktx
git checkout develop

Gradle

The project itself is managed by Gradle. Gradle wrapper is included, but you can use a local Gradle installation - scripts should be compatible with Gradle 6.+. Gradle projects are handled out of the box by IntelliJ, so KTX should be relatively easy to import.

Some useful Gradle tasks include:

• build install - builds the libraries archives and pushes them to Maven Local. Useful for local tests.
• format - formats all Kotlin source files.
• linterIdeSetup - modifies local IntelliJ project setup for consistency with ktlint formatting.
• check - runs all tests in all projects.
• clean - removes the build directories, which forces rebuilds of the modules.
• distZip - prepares a zip archive with all jars in build/distributions folder. Useful for releases.
• publish - pushes the archives to Maven Central or the snapshot repository, depending on the version. Requires complete gradle.properties with archive signing and Sonatype logging data.
• closeAndReleaseRepository - closes and releases the Nexus repository. Should be run after publish in case of a non-snapshot upload to Maven Central. Might fail at times on the release task; running releaseRepository separately should fix the issue.

Adding a new KTX module

• Create a folder matching module name in root of the repository. Modules should generally be named with a single word. When multiple words are necessary, use a single dash (-) as the word separator.
• Add folder name to settings.gradle.kts file. This will also serve as the project identifier that you use in build.gradle scripts and to run individual Gradle tasks (e.g. gradle actors:test).
• Create src/main/kotlin and src/test/kotlin directories in your module folder. They will be automatically marked as source thanks to Gradle. You should also create package structure matching ktx/your/module in each source folder.
• Add gradle.properties file with the following properties:

projectName=ktx-your-module
projectDesc=Description of your module as it will appear in Maven Central.

• Add a build.gradle.kts file. It should contain dependencies specific to your module. If there are none, you can leave it empty. By adding import ktx.* at the top of this file, you will be able to access the versions of major dependencies of the modules as defined in the buildSrc directory.
• Add a README.md file describing your module. Refer to other README.md files for guidelines. README.md files should generally consist of the following sections:
  • General description - in a single sentence, what problem does the module solve?
  • Motivation - why was the module created?
  • Guide - what features does the module provide? Does it require additional setup?
  • Usage examples - how to use the module?
  • Synergy - is the module complemented by any other KTX libraries?
  • Alternatives - are there any other libraries or modules that can be used instead?
  • Additional documentation - are there any other guides or articles on the topic?
• Add Maven Central badge to the top of the README.md to ease inclusion of the library:

[![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-your-module.svg)](https://search.maven.org/artifact/io.github.libktx/ktx-your-module)

• Your final module structure should roughly match this schema:

> your-module/
  > src/
    > main/kotlin/ktx/your/module/
      - yourModule.kt
    > test/kotlin/ktx/your/module/
      - yourModuleTest.kt
  - build.gradle.kts
  - gradle.properties
  - README.md

Maintenance

The following sections are for the maintainers of the repository.

Updating dependencies

Kotlin and plugin versions are stored in the gradle.properties file, while module dependencies versions are stored with the Versions.kt file. Snapshot releases should keep all the dependencies (outside of testing scope) up-to-date. Major dependencies include:

• LibGDX: update gdxVersion in the versions file and LibGDX version in the tag on the top of the README.md file. Note that updating LibGDX also affects the KTX version and milestones, so make sure to update the version.txt and milestones as well.
• Kotlin: update the kotlinVersion in the properties file and the Kotlin tag in the README.md.
• Kotlin Coroutines: update kotlinCoroutinesVersion in the versions file and the tag in the ktx-async README.md.
• Gradle: run gradle wrapper in the root project folder. Make sure that the Gradle wrapper properties file points the all Gradle release under distributionUrl rather than just the binaries (bin).
• VisUI: update visUiVersion in the versions file and VisUI version in the tag on the top of the vis/README.md file.
• Ashley: update ashleyVersion in the versions file and Ashely version in the tag on the top of the ashley/README.md file.

All the major dependencies updates should be added to the changelog.

Versioning and uploading

Stable release

• Create a new issue on GitHub. Include the number of the issue in commit messages of all commits related to the release. Apply dev label and milestone corresponding to the LibGDX version. An example can be found here.
• Change libVersion setting in the version.txt. KTX uses the same versioning schema as LibGDX (mimicking the LibGDX version that it was compiled against) with a suffix depending on the version status.
• Create a pull request from the develop branch to the master branch. Review and merge the changes to the master branch.
• Checkout the master branch. Fetch the latest changes.
• Run gradle build publish closeAndReleaseRepository to push artifacts to Maven Central. Note that the Maven plugin has its issues and might fail with an error, but usually the release will be successful. You can check if the staging repository was properly close, promoted and released at Nexus Repository Manager.
• Run gradle distZip to prepare an archive with KTX sources, compiled binary and documentation.
• Upload the archive to releases section. The tag should be made from the master branch and its name should match the released version. Name of the release should match KTX $libVersion. Add a short release summary and copy the latest changelog entries to the release description.
• If there are any known issues with the previous or current versions, please attach additional Known issues: section with the following labels:
  • [BUG] - a known bug in the release that is or will be fixed in the following versions.
  • [INCOMPATIBILITY] - incompatibility with one of the previously supported or currently released versions of one of the major dependencies.
  • [REMOVAL] - temporary or permanent removal of a major feature (e.g. disabling a module for a single release).
• Checkout the develop branch.
• Change libVersion setting in the version.txt to the next snapshot release. The name should match the used LibGDX version followed by the -SNAPSHOT suffix.

Snapshot release

• Make sure the version.txt ends with the -SNAPSHOT suffix and matches the LibGDX version that the library was compiled against.
• Run gradle build uploadSnapshot to push artifacts to Sonatype snapshots repository. This task will do nothing if the current version is not a snapshot to avoid accidentally pushing a stable release.

Note that snapshots are automatically uploaded to Maven Central (OSS Sonatype) snapshots repository after pushing to the develop branch.

Automated tasks

Tasks automated with GitHub actions:

• build - compiles and tests all KTX modules. Triggered by pushing and setting up pull requests to master and develop branches.
• upload-snapshot - compiles all KTX modules and uploads a new snapshot release. Triggered by pushing to the develop branch.
• publish-documentation - builds and replaces the Dokka documentation published to the official website. Triggered by pushing to the master branch, which is generally only done before stable releases.