From 50d736091f35e3670a5a612d624859c92f5e566e Mon Sep 17 00:00:00 2001 From: zaleslaw Date: Thu, 2 Feb 2023 16:45:31 +0100 Subject: [PATCH 1/3] Added a CONTRIBUTING.md --- CONTRIBUTING.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..923d5c6a2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Contributing Guidelines + +There are two main ways to contribute to the project — submitting issues and submitting +fixes/changes/improvements via pull requests. + +## Submitting issues + +Both bug reports and feature requests are welcome. +Submit issues [here](https://github.com/Kotlin/dataframe/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 already fixed. + * Include the code that reproduces the problem or attach the link to the repository with the project which fully reproduces the problem. + * However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently + reproduce them. + * If the bug is in behavior, then explain what behavior you've expected and what you've got. +* When submitting a feature request: + * Explain why you need the feature — what's your use-case, what's your domain. + * Explaining the problem you face is more important than suggesting a solution. + Report your issue even if you don't have any proposed solution. + * If there is an alternative way to do what you need, then show the code of the alternative. + +## Submitting PRs + +We love PRs. Submit PRs [here](https://github.com/Kotlin/dataframe/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. + +* All development (both new features and bug fixes) is performed in the `master` branch. + * Base PRs against the `master` branch. + * PR should be linked with the issue, + excluding minor documentation changes, the addition of unit tests, and fixing typos. +* If you make any code changes: + * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). + * [Build the project](#building) to make sure it all works and passes the tests. +* If you fix a bug: + * Write the test the 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. +* If you introduce any new public APIs: + * All new APIs must come with documentation and tests. + * If you plan 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 big piece of work in advance via submitting an issue. +* If you fix documentation: + * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers) + to coordinate the work in advance. + +## PR workflow + +0. Contributor build the library locally and run all unit test via Gradle task `dataframe:test` + (see the ["Building"](#building) chapter). +1. Contributor submits the PR if the local build is successful and tests are green. +2. Reviewer put his name to the "Reviewers" section of the proposed PR at the start of the review process. +3. Reviewer leaves the comments or marks the PR with the word "LGTM." +4. Contributor answers the comments or fixes the proposed PR. +5. Reviewer marks the PR with the word "LGTM." +6. Maintainer could suggest merging the master branch to the PR branch a few times due to changes in the `master` branch. +7. Maintainer runs TC builds (unit tests and examples as integration tests). +8. The TC writes the result (passed or not passed) to the PR checks at the bottom of the proposed PR. +9. If it is possible, maintainers share the details of the failed build with the contributor. +10. Maintainer merges the PR if all checks are successful and there is no conflict with the master branch. + +## How to fix an existing issue + +* If you are going to work on the existing issue: + * Comment on the existing issue if you want to work on it. + * Wait till it is assigned to you by [maintainers](#contacting-maintainers). + * Ensure that the issue not only describes a problem, but also describes a solution that had received a positive feedback. Propose a solution if there isn't any. +* If you are going to submit your first PR in this project: + * 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) + which are not assigned to somebody. + * Learn the [`examples`](https://github.com/Kotlin/dataframe/tree/master/examples) module, submit new interesting example or improve documentation for one of them. +* If you are ready to participate in library design and in new experiments, find tickets with the label + ["research"](https://github.com/Kotlin/dataframe/issues?q=is%3Aissue+is%3Aopen+label%3Aresearch) + or join to our [discussions](https://github.com/Kotlin/dataframe/discussions). + +## Environment requirements + +JDK >= 11 referred to by the `JAVA_HOME` environment variable. + +## Building + +This library is built with Gradle. + +* Run `./gradlew build` to build. It also runs all the tests. +* Run `./gradlew :test` to test the module you are looking at to speed + things up during development. + +You can import this project into IDEA, but you have to delegate build actions +to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Runner) + +## Contacting maintainers + +* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). +* To attract attention to the problem or raised question or a new comment, mention one of us on the Github: @koperagen @Jolanrensen @zaleslaw @ileasile +* "How to do something" questions — [StackOverflow](https://stackoverflow.com). +* Discussions and general inquiries — use `#datascience` channel in [KotlinLang Slack](https://kotl.in/slack). From 003f53fb7f165d5edbffb77b04b8429c22b39df1 Mon Sep 17 00:00:00 2001 From: zaleslaw Date: Fri, 3 Feb 2023 14:52:31 +0100 Subject: [PATCH 2/3] Fixed the review --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 923d5c6a2..e21f51ab6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,6 +46,7 @@ so do familiarize yourself with the following guidelines. * If you fix documentation: * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers) to coordinate the work in advance. + * Also, we have a special simple [guide](https://github.com/Kotlin/dataframe/blob/master/docs/contributions.md) how to contribute in the documentation. ## PR workflow @@ -95,5 +96,4 @@ to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Grad * If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). * To attract attention to the problem or raised question or a new comment, mention one of us on the Github: @koperagen @Jolanrensen @zaleslaw @ileasile -* "How to do something" questions — [StackOverflow](https://stackoverflow.com). * Discussions and general inquiries — use `#datascience` channel in [KotlinLang Slack](https://kotl.in/slack). From 1997c0fbc46ce5a5724e4cc4afe6a1d3b03cf872 Mon Sep 17 00:00:00 2001 From: zaleslaw Date: Mon, 6 Feb 2023 12:52:37 +0100 Subject: [PATCH 3/3] Fixed the review and some grammar issues --- CONTRIBUTING.md | 50 +++++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e21f51ab6..5ae2a9adb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,16 +10,17 @@ Submit issues [here](https://github.com/Kotlin/dataframe/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 already fixed. - * Include the code that reproduces the problem or attach the link to the repository with the project which fully reproduces the problem. + * Test it against the most recently released version. It might have already been fixed. + * Include the code reproducing the problem or attach the link to the repository with the project that fully reproduces the problem. * However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently reproduce them. * If the bug is in behavior, then explain what behavior you've expected and what you've got. * When submitting a feature request: - * Explain why you need the feature — what's your use-case, what's your domain. + * Explain why you need the feature &mdash, your use case, and your domain. * Explaining the problem you face is more important than suggesting a solution. Report your issue even if you don't have any proposed solution. - * If there is an alternative way to do what you need, then show the code of the alternative. + * If there is an alternative way to do what you need, show the alternative's code. + ## Submitting PRs @@ -30,19 +31,19 @@ so do familiarize yourself with the following guidelines. * All development (both new features and bug fixes) is performed in the `master` branch. * Base PRs against the `master` branch. * PR should be linked with the issue, - excluding minor documentation changes, the addition of unit tests, and fixing typos. + excluding minor documentation changes, adding unit tests, and fixing typos. * If you make any code changes: * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). - * [Build the project](#building) to make sure it all works and passes the tests. + * [Build the project](#building) to ensure it all works and passes the tests. * If you fix a bug: - * Write the test the reproduces the bug. + * 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. * If you introduce any new public APIs: * All new APIs must come with documentation and tests. - * If you plan API additions, then please start by submitting an issue with the proposed API design + * If you plan API additions, please start by submitting an issue with the proposed API design to gather community feedback. - * [Contact the maintainers](#contacting-maintainers) to coordinate any big piece of work in advance via submitting an issue. + * [Contact the maintainers](#contacting-maintainers) to coordinate any great work in advance via submitting an issue. * If you fix documentation: * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers) to coordinate the work in advance. @@ -50,15 +51,15 @@ so do familiarize yourself with the following guidelines. ## PR workflow -0. Contributor build the library locally and run all unit test via Gradle task `dataframe:test` +0. The contributor builds the library locally and runs all unit tests via the Gradle task `dataframe:test` (see the ["Building"](#building) chapter). -1. Contributor submits the PR if the local build is successful and tests are green. -2. Reviewer put his name to the "Reviewers" section of the proposed PR at the start of the review process. -3. Reviewer leaves the comments or marks the PR with the word "LGTM." -4. Contributor answers the comments or fixes the proposed PR. -5. Reviewer marks the PR with the word "LGTM." -6. Maintainer could suggest merging the master branch to the PR branch a few times due to changes in the `master` branch. -7. Maintainer runs TC builds (unit tests and examples as integration tests). +1. The contributor submits the PR if the local build is successful and the tests are green. +2. The reviewer put his name in the "Reviewers" section of the proposed PR at the start of the review process. +3. The reviewer leaves the comments or marks the PR with the abbreviation "LGTM" (Looks good to me). +4. The contributor answers the comments or fixes the proposed PR. +5. The reviewer marks the PR with the word "LGTM." +6. The maintainer could suggest merging the master branch to the PR branch a few times due to changes in the `master` branch. +7. The maintainer runs TC builds (unit tests and examples as integration tests). 8. The TC writes the result (passed or not passed) to the PR checks at the bottom of the proposed PR. 9. If it is possible, maintainers share the details of the failed build with the contributor. 10. Maintainer merges the PR if all checks are successful and there is no conflict with the master branch. @@ -68,14 +69,15 @@ so do familiarize yourself with the following guidelines. * If you are going to work on the existing issue: * Comment on the existing issue if you want to work on it. * Wait till it is assigned to you by [maintainers](#contacting-maintainers). - * Ensure that the issue not only describes a problem, but also describes a solution that had received a positive feedback. Propose a solution if there isn't any. + * Ensure that the issue describes a problem and a solution that has received positive feedback. Propose a solution if there isn't any. * If you are going to submit your first PR in this project: * 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) which are not assigned to somebody. - * Learn the [`examples`](https://github.com/Kotlin/dataframe/tree/master/examples) module, submit new interesting example or improve documentation for one of them. -* If you are ready to participate in library design and in new experiments, find tickets with the label + * Learn the [`examples`](https://github.com/Kotlin/dataframe/tree/master/examples) module. Submit an interesting new example or improve documentation for one of them. +* If you are ready to participate in library design and new experiments, find tickets with the label ["research"](https://github.com/Kotlin/dataframe/issues?q=is%3Aissue+is%3Aopen+label%3Aresearch) - or join to our [discussions](https://github.com/Kotlin/dataframe/discussions). + or join our [discussions](https://github.com/Kotlin/dataframe/discussions). + ## Environment requirements @@ -89,11 +91,11 @@ This library is built with Gradle. * Run `./gradlew :test` to test the module you are looking at to speed things up during development. -You can import this project into IDEA, but you have to delegate build actions +You can import this project into IDEA, but you have to delegate the build actions to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Runner) ## Contacting maintainers -* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). -* To attract attention to the problem or raised question or a new comment, mention one of us on the Github: @koperagen @Jolanrensen @zaleslaw @ileasile +* If something cannot be done or doesn't work conveniently — submit an [issue](#submitting-issues). +* To attract attention to your problem, raise a question, or make a new comment, mention one of us on Github: @koperagen @Jolanrensen @zaleslaw @ileasile * Discussions and general inquiries — use `#datascience` channel in [KotlinLang Slack](https://kotl.in/slack).