1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
# 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](https://github.com/Kotlin/dokka/issues).
* 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](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/) documentation
which goes over the development [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) and
[Dokka's architecture](https://kotlin.github.io/dokka/1.7.20/developer_guide/architecture/architecture_overview/),
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](https://kotlinlang.org/docs/reference/coding-conventions.html).
Use 4 spaces for indentation.
* [Build the project](#building) 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](#updating-public-api-dump), otherwise it will fail
the build.
Please [contact maintainers](#contacting-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:
```Bash
./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](https://kotlin.github.io/dokka/1.7.20/developer_guide/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.7.20-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:
```kotlin
plugins {
id("org.jetbrains.dokka") version "1.7.20-my-fix-SNAPSHOT"
}
```
### Updating public API dump
[Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md)
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](#submitting-issues).
* Discussions and general inquiries — use `#dokka` channel in
[Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up).
|
