Skip to content

Latest commit

 

History

History
89 lines (65 loc) · 4.1 KB

CONTRIBUTING.md

File metadata and controls

89 lines (65 loc) · 4.1 KB
Raw

Contributing Guidelines

There are three main ways you can contribute to Dokka's development:

  • Submitting issues.
  • Submitting fixes/changes/improvements via pull requests.
  • Developing community plugins.

Submitting issues

Bug reports, feature requests and questions are welcome. Submit issues here.

  • Search for existing issues to avoid reporting duplicates.
  • When submitting a bug report:
    • Test it against the most recently released version. It might have been fixed already.
    • Include code that reproduces the problem. Provide a complete reproducer, yet minimize it as much as possible. A separate project that can be cloned is ideal.
    • If the bug is in behavior, explain what behavior you expected and what the actual result is.
  • When submitting a feature request:
    • Explain why you need the feature.
    • Explaining the problem you face is more important than suggesting a solution. Report your problem even if you have no proposed solution.

Submitting PRs

Dokka has extensive Developer Guides documentation which goes over the development Workflow and Dokka's architecture, which can help you understand how to achieve what you want and where to look.

All development (both new features and bugfixes) takes place in the master branch, it contains sources for the next version of Dokka.

For any code changes:

  • Follow Kotlin Coding Conventions. Use 4 spaces for indentation.
  • Build the project to make sure it all works and tests pass.
  • Write tests that reproduce the bug or test new features.
  • PRs without tests are accepted only in exceptional circumstances if it is evident that writing the corresponding test is too hard or otherwise impractical.
  • If you add new or change old public API, update public API dump, otherwise it will fail the build.

Please contact maintainers in advance to coordinate any big piece of work.

Building

Building Dokka is pretty straightforward, with one small caveat: when you run ./gradlew build, it will run integration tests as well, which might take some time and will consume a lot of RAM (~20-30 GB), so you would usually want to exclude integration tests when building locally:

./gradlew build -x integrationTest

Unit tests which are run as part of build should not take much time, but you can also skip it with -x test.

Using/testing locally built Dokka

Below you will find a bare-bones instruction on how to use and test locally built Dokka. For more details and examples, visit Workflow topic.

  1. Change dokka_version in gradle.properties to something that you will use later on as the dependency version. For instance, you can set it to something like 1.8.10-my-fix-SNAPSHOT.
  2. Publish it to Maven Local (./gradlew publishToMavenLocal)
  3. In the project for which you want to generate documentation add Maven Local as a buildscript/dependency repository (mavenLocal())
  4. Update your Dokka dependency to the version you've just published:
plugins {
    id("org.jetbrains.dokka") version "1.8.10-my-fix-SNAPSHOT"
}

Updating public API dump

Binary Compatibility Validator is used to keep track of public API changes.

Run ./gradlew apiDump to update API index files after introducing new or changing old public API. Commit updated API indexes together with other changes.

Contacting maintainers

  • If something cannot be done, not convenient, or does not work — submit an issue.
  • Discussions and general inquiries — use #dokka channel in Kotlin Community Slack.