Skip to content

Update the contribution guidelines #4458

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update the contribution guidelines #4458

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 24 additions & 22 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,27 @@ Both bug reports and feature requests are welcome.
Submit issues [here](https://github.com/Kotlin/kotlinx.coroutines/issues).
Questions about usage and general inquiries are better suited for [StackOverflow](https://stackoverflow.com)
or the `#coroutines` channel in [KotlinLang Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up).
There, questions get answered much quicker than they do in this issue tracker,
while also reducing the load on the maintainers.

### Commenting on issues

Describing why you're interested in some specific issue helps us a lot with looking for the best solution.
The more experiences, concerns, or suggestions get shared, the better!
If you feel that something you know hasn't been said (or even if the issue discussion is too long to actually
make sure of it), please do not hesitate to drop a line.

On the other hand, "+1"-style remarks or questions about the progress on an issue do not bring anything new
and only create noise, complicating the job of finding insight in the discussion.
Please avoid this. We reserve the right to delete such comments.

## Submitting PRs

We love PRs. Submit PRs [here](https://github.com/Kotlin/kotlinx.coroutines/pulls).
However, please keep in mind that maintainers will have to support the resulting code of the project,
so do familiarize yourself with the following guidelines.

* Before introducing a code change,
* All development (both new features and bug fixes) is performed in the `develop` branch.
* The `master` branch contains the sources of the most recently released version.
* Base your PRs against the `develop` branch.
Expand All @@ -35,48 +49,36 @@ so do familiarize yourself with the following guidelines.
then separate them with a comment instead.
* [Build the project](#building) to make sure everything works and passes the tests.
* If you fix a bug:
* Note that what is a bug for some can be a feature for others.
Are you truly fixing a problem? Is there an open issue about it?
* Write the test that reproduces the bug.
* Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the
corresponding test is too hard or otherwise impractical.
* Follow the style of writing tests that is used in this project:
name test functions as `testXxx`. Don't use backticks in test names.
* If you introduce any new public APIs:
* Comment on the existing issue if you want to work on it or create one beforehand.
Ensure that not only the issue describes a problem, but also that the proposed solution has received positive
feedback. Propose a solution if there isn't any.
PRs that add new API without a corresponding issue with positive feedback about the proposed implementation are
unlikely to be approved or reviewed.
* Before setting out to work on a problem, comment on the existing issue or create one,
proposing a solution and gathering feedback first before implementing it.
PRs that add new API without the corresponding issue with positive feedback about the proposed implementation are
very unlikely to be approved or reviewed.
* All new APIs must come with documentation and tests.
* All new APIs are initially released with the `@ExperimentalCoroutineApi` annotation and graduate later.
* [Update the public API dumps](#updating-the-public-api-dump) and commit the resulting changes as well.
It will not pass the tests otherwise.
* If you plan large API additions, then please start by submitting an issue with the proposed API design
to gather community feedback.
* [Contact the maintainers](#contacting-maintainers) to coordinate any extensive work in advance.

## Building

This library is built with Gradle.

* Run `./gradlew build` to build. It also runs all the tests.
* Run `./gradlew <module>:check` to test the module you are looking at to speed
* Run `./gradlew build` to build, also running all of the tests.
* Run `./gradlew <module>:check` to test the module you are working with to speed
things up during development.
* Run `./gradlew <module>:jvmTest` to perform only the fast JVM tests of a multiplatform module.

You can import this project into IDEA, but you have to delegate build actions
to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Build and run).
* Run `./gradlew <module>:jvmTest -Pstress=true` to run both fast and slow JVM tests.

### Environment requirements

* JDK >= 11 referred to by the `JAVA_HOME` environment variable.
* JDK 1.8 referred to by the `JDK_18` environment variable. Only used by nightly stress-tests.
It is OK to have `JDK_18` point to a non-1.8 JDK (e.g. `JAVA_HOME`) for external contributions.

For external contributions you can, for example, add this to your shell startup scripts (e.g. `~/.zshrc`):
```shell
# This assumes JAVA_HOME is set already to a JDK >= 11 version
export JDK_18="$JAVA_HOME"
```
JDK >= 11 referred to by the `JAVA_HOME` environment variable.

### Running the Knit tool

Expand Down