1# Contributing Guidelines 2 3There are two main ways to contribute to the project — submitting issues and submitting 4fixes/changes/improvements via pull requests. 5 6## Submitting issues 7 8Both bug reports and feature requests are welcome. 9Submit issues [here](https://github.com/Kotlin/kotlinx.serialization/issues). 10 11* Search for existing issues to avoid reporting duplicates. 12* When submitting a bug report: 13 * Use a 'bug report' template when creating a new issue. 14 * Test it against the most recently released version. It might have been already fixed. 15 * By default, we assume that your problem reproduces in Kotlin/JVM. Please, mention if the problem is 16 specific to Kotlin/JS or Kotlin/Native. 17 * Include the code that reproduces the problem. Provide the complete reproducer code, yet minimize it as much as possible. 18 * However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently 19 reproduce them. 20 * If the bug is in behavior, then explain what behavior you've expected and what you've got. 21* When submitting a feature request: 22 * Use a 'feature request' template when creating a new issue. 23 * Explain why you need the feature — what's your use-case, what's your domain. 24 * Explaining the problem you face is more important than suggesting a solution. 25 Even if you don't have a proposed solution, please report your problem. 26 * If there is an alternative way to do what you need, then show the code of the alternative. 27 28## Submitting PRs 29 30We love PRs. Submit PRs [here](https://github.com/Kotlin/kotlinx.serialization/pulls). 31However, please keep in mind that maintainers will have to support the resulting code of the project, 32so do familiarize yourself with the following guidelines. 33 34* All development (both new features and bug fixes) is performed in the `dev` branch. 35 * The `master` branch always contains sources of the most recently released version. 36 * Base PRs against the `dev` branch. 37 * The `dev` branch is pushed to the `master` branch during release. 38 * Documentation in markdown files can be updated directly in the `master` branch, 39 unless the documentation is in the source code, and the patch changes line numbers. 40* If you fix documentation: 41 * After fixing/changing code examples in the [`docs`](docs) folder or updating any references in the markdown files 42 run the [Knit tool](#running-the-knit-tool) and commit the resulting changes as well. 43 Your changes will not pass the tests otherwise. 44 * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers) 45 to coordinate the work in advance. 46* If you make any code changes: 47 * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). 48 * Use 4 spaces for indentation. 49 * Use imports with '*'. 50 * [Build the project](#building) to make sure it all works and passes the tests. 51* If you fix a bug: 52 * Write the test that reproduces the bug. 53 * Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the 54 corresponding test is too hard or otherwise impractical. 55 * Follow the style of writing tests that is used in this project: 56 name test functions as `testXxx`. Don't use backticks in test names. 57* If you introduce any new public APIs: 58 * All new APIs must come with documentation and tests. 59 * All new APIs are initially released with `@ExperimentalSerializationApi` annotation and are graduated later. 60 * [Update the public API dumps](#updating-the-public-api-dump) and commit the resulting changes as well. 61 It will not pass the tests otherwise. 62 * If you plan large API additions, then please start by submitting an issue with the proposed API design 63 to gather community feedback. 64 * [Contact the maintainers](#contacting-maintainers) to coordinate any big piece of work in advance. 65* If you propose/implement a new serialization format: 66 * Follow the general advice on new public APIs above. 67 * Note, that you can keep new format implementation in your own repository to be able to perform proper maintenance 68 and to have a separate release cycle. 69 * You can submit a PR to the [list of community-supported formats](formats/README.md#other-community-supported-formats) 70 with a description of your library. 71* Comment on the existing issue if you want to work on it. Ensure that the issue not only describes a problem, 72 but also describes a solution that has received positive feedback. Propose a solution if there isn't any. 73 74## Building 75 76You can find all the instructions [here](docs/building.md) 77 78### Running the Knit tool 79 80* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/master/README.md) for updates to documentation: 81 * Run `./gradlew knit` to update example files, links, tables of content. 82 * Commit updated documents and examples together with other changes. 83 84### Updating the public API dump 85 86* Use [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API: 87 * Run `./gradlew apiDump` to update API index files. 88 * Commit updated API indexes together with other changes. 89 90## Releases 91 92* Full release procedure checklist is [here](RELEASING.md). 93 94## Contacting maintainers 95 96* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). 97* "How to do something" questions — [StackOverflow](https://stackoverflow.com). 98* Discussions and general inquiries — use `#serialization` channel in [KotlinLang Slack](https://kotl.in/slack). 99 100