|
| 1 | +# Contributing Guidelines |
| 2 | + |
| 3 | +There are two main ways to contribute to the project — submitting issues and submitting |
| 4 | +fixes/changes/improvements via pull requests. |
| 5 | + |
| 6 | +## Submitting issues |
| 7 | + |
| 8 | +Both bug reports and feature requests are welcome. |
| 9 | +Submit issues [here](https://github.com/Kotlin/dataframe/issues). |
| 10 | + |
| 11 | +* Search for existing issues to avoid reporting duplicates. |
| 12 | +* When submitting a bug report: |
| 13 | + * Test it against the most recently released version. It might have already been fixed. |
| 14 | + * Include the code reproducing the problem or attach the link to the repository with the project that fully reproduces the problem. |
| 15 | + * However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently |
| 16 | + reproduce them. |
| 17 | + * If the bug is in behavior, then explain what behavior you've expected and what you've got. |
| 18 | +* When submitting a feature request: |
| 19 | + * Explain why you need the feature &mdash, your use case, and your domain. |
| 20 | + * Explaining the problem you face is more important than suggesting a solution. |
| 21 | + Report your issue even if you don't have any proposed solution. |
| 22 | + * If there is an alternative way to do what you need, show the alternative's code. |
| 23 | + |
| 24 | + |
| 25 | +## Submitting PRs |
| 26 | + |
| 27 | +We love PRs. Submit PRs [here](https://github.com/Kotlin/dataframe/pulls). |
| 28 | +However, please keep in mind that maintainers will have to support the resulting code of the project, |
| 29 | +so do familiarize yourself with the following guidelines. |
| 30 | + |
| 31 | +* All development (both new features and bug fixes) is performed in the `master` branch. |
| 32 | + * Base PRs against the `master` branch. |
| 33 | + * PR should be linked with the issue, |
| 34 | + excluding minor documentation changes, adding unit tests, and fixing typos. |
| 35 | +* If you make any code changes: |
| 36 | + * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). |
| 37 | + * [Build the project](#building) to ensure it all works and passes the tests. |
| 38 | +* If you fix a bug: |
| 39 | + * Write the test that reproduces the bug. |
| 40 | + * Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the |
| 41 | + corresponding test is too hard or otherwise impractical. |
| 42 | +* If you introduce any new public APIs: |
| 43 | + * All new APIs must come with documentation and tests. |
| 44 | + * If you plan API additions, please start by submitting an issue with the proposed API design |
| 45 | + to gather community feedback. |
| 46 | + * [Contact the maintainers](#contacting-maintainers) to coordinate any great work in advance via submitting an issue. |
| 47 | +* If you fix documentation: |
| 48 | + * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers) |
| 49 | + to coordinate the work in advance. |
| 50 | + * Also, we have a special simple [guide](https://github.com/Kotlin/dataframe/blob/master/docs/contributions.md) how to contribute in the documentation. |
| 51 | + |
| 52 | +## PR workflow |
| 53 | + |
| 54 | +0. The contributor builds the library locally and runs all unit tests via the Gradle task `dataframe:test` |
| 55 | + (see the ["Building"](#building) chapter). |
| 56 | +1. The contributor submits the PR if the local build is successful and the tests are green. |
| 57 | +2. The reviewer put his name in the "Reviewers" section of the proposed PR at the start of the review process. |
| 58 | +3. The reviewer leaves the comments or marks the PR with the abbreviation "LGTM" (Looks good to me). |
| 59 | +4. The contributor answers the comments or fixes the proposed PR. |
| 60 | +5. The reviewer marks the PR with the word "LGTM." |
| 61 | +6. The maintainer could suggest merging the master branch to the PR branch a few times due to changes in the `master` branch. |
| 62 | +7. The maintainer runs TC builds (unit tests and examples as integration tests). |
| 63 | +8. The TC writes the result (passed or not passed) to the PR checks at the bottom of the proposed PR. |
| 64 | +9. If it is possible, maintainers share the details of the failed build with the contributor. |
| 65 | +10. Maintainer merges the PR if all checks are successful and there is no conflict with the master branch. |
| 66 | + |
| 67 | +## How to fix an existing issue |
| 68 | + |
| 69 | +* If you are going to work on the existing issue: |
| 70 | + * Comment on the existing issue if you want to work on it. |
| 71 | + * Wait till it is assigned to you by [maintainers](#contacting-maintainers). |
| 72 | + * Ensure that the issue describes a problem and a solution that has received positive feedback. Propose a solution if there isn't any. |
| 73 | +* If you are going to submit your first PR in this project: |
| 74 | + * Find tickets with the label ["good first issue"](https://github.com/Kotlin/dataframe/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee) |
| 75 | + which are not assigned to somebody. |
| 76 | + * Learn the [`examples`](https://github.com/Kotlin/dataframe/tree/master/examples) module. Submit an interesting new example or improve documentation for one of them. |
| 77 | +* If you are ready to participate in library design and new experiments, find tickets with the label |
| 78 | + ["research"](https://github.com/Kotlin/dataframe/issues?q=is%3Aissue+is%3Aopen+label%3Aresearch) |
| 79 | + or join our [discussions](https://github.com/Kotlin/dataframe/discussions). |
| 80 | + |
| 81 | + |
| 82 | +## Environment requirements |
| 83 | + |
| 84 | +JDK >= 11 referred to by the `JAVA_HOME` environment variable. |
| 85 | + |
| 86 | +## Building |
| 87 | + |
| 88 | +This library is built with Gradle. |
| 89 | + |
| 90 | +* Run `./gradlew build` to build. It also runs all the tests. |
| 91 | +* Run `./gradlew <module>:test` to test the module you are looking at to speed |
| 92 | + things up during development. |
| 93 | + |
| 94 | +You can import this project into IDEA, but you have to delegate the build actions |
| 95 | +to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Runner) |
| 96 | + |
| 97 | +## Contacting maintainers |
| 98 | + |
| 99 | +* If something cannot be done or doesn't work conveniently — submit an [issue](#submitting-issues). |
| 100 | +* To attract attention to your problem, raise a question, or make a new comment, mention one of us on Github: @koperagen @Jolanrensen @zaleslaw @ileasile |
| 101 | +* Discussions and general inquiries — use `#datascience` channel in [KotlinLang Slack](https://kotl.in/slack). |
0 commit comments