Kotlin project skeleton

Kotlin project blueprint, including common dependencies.

Report Bug · Request Feature · Changelog

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Contributing
4. License
5. Contact

About The Project

This project was meant to help us get new project initialized faster; it should be understand as a blueprint for all kind of projects written in Kotlin.

You may abstract the list of included plugins and dependencies from the io.mailguru.gradle-config plugin page.

Versioning strategy

This library uses Semantic Versioning 2.0 and generates its Changelog from Conventional Commit messages.

(back to top)

Getting Started

Prerequisites

We choose to support the lowest actively supported Java version at the time of writing, that is, Java 11 (this may be subject to change in future major releases).

Installation

Since this project isn't going to be released at maven central (because that wouldn't make any sense), you may clone the latest develop branch of this repository, do some cleanup, and start your work from a clean local git repo:

git clone https://github.com/mlgr-io/kotlin-skeleton.git your-desired-project-folder

cd your-desired-project-folder

git remote rm origin

# Optional steps to prepare your local copy of the repository for your own project:

# Remove all tags
git tag | xargs git tag -d

# Squash the whole history into a single commit
git reset $(git commit-tree HEAD^{tree} -m "feat: initial commit")

You may also want to replace your copy of CHANGELOG.md by a clean stub (the "draft new release" GitHub action expects at least such a stub and will throw an error if the file is missing or not well-formatted).

(Semi-)Automatic Releases, Changelog generation and maven publication

This project includes GitHub actions that create releases, update the docs and publish your artifacts to a maven registry. For publishing, please see the following section. For information on how creating releases works, please see the official documentation of the GitFlow release workflow using GitHub actions.

Publishing signed artifacts to an arbitrary maven registry

If you want your code to be packed, signed and published (and closed and released) to maven central on a release, you'll have to deposit the required secrets at your GitHub repository. The following secrets are required for that GitHub action to work (we assume that you're familiar with GPG and already have generated a key pair; if not, please have a look at the Central Repository GPG guide):

• GPG_KEY_ID The short (8 chars) key ID of your GPG key; on macOS, you may retrieve the key ID by executing

  gpg --list-secret-keys --keyid-format short | grep sec | cut -d' ' -f 4 | cut -d'/' -f 2`

• GPG_SIGNING_KEY The GPG signing key, encoded as Base64. You will most likely get this information by executing

  cat ~/.gnupg/secring.gpg | base64

• GPG_PASSPHRASE The passphrase for your preceding GPG key, as chosen on key pair generation.
• MAVEN_CENTRAL_USERNAME The username for your publication target maven registry.
  The example build.gradle.kts is configured to publish to https://s01.oss.sonatype.org.
• MAVEN_CENTRAL_PASSWORD The password for the maven registry, related to MAVEN_CENTRAL_USERNAME.

To make sure everything works as expected, we strongly recommend to disable the closeAndReleaseRepository task on your first publication(s):

To remove the auto-close-and-release behaviour, please remove (or comment) the closeAndReleaseRepository gradle task from release-publish.yml (nearly at the end). After disabling, you have to close and release your artifact manually from your staging repository at the sonatype registry (only if you published to their registry, of course).

If you want to remove auto-publishing completely (that is, no maven publish on a finished release), please delete the publish job from the release-publish.yml (starting from L59) action configuration.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/YourAmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/YourAmazingFeature)
5. Open a Pull Request

There is also an excellent step-by-step guide written by James Priest.

(back to top)

License

Distributed under the GNU General Public License v3.0. See LICENSE.md for more information.

(back to top)

Contact

Project Link: https://github.com/mlgr-io/kotlin-skeleton

(back to top)