From f3ee4d08842f8ad8f18bab69378c8b322f677996 Mon Sep 17 00:00:00 2001 From: Stijn de Gooijer Date: Mon, 30 Oct 2023 18:10:53 +0100 Subject: [PATCH] docs: Consolidate contributing info (#12109) --- Cargo.toml | 1 - contribution/README.md | 28 ---------------- .../polars_ops_multiple_arguments/Cargo.toml | 8 ----- docs/_build/snippets/under_construction.md | 2 +- .../development/contributing/ci.md | 9 +++--- .../development/contributing/code-style.md | 27 ++++++++++++++++ docs/development/contributing/ide.md | 32 +++++++++++++++++++ .../index.md} | 2 +- .../development/contributing/test.md | 26 ++++++++------- docs/index.md | 2 +- mkdocs.yml | 7 +++- 11 files changed, 87 insertions(+), 57 deletions(-) delete mode 100644 contribution/README.md delete mode 100644 contribution/polars_ops_multiple_arguments/Cargo.toml rename .github/workflows/README.md => docs/development/contributing/ci.md (89%) rename contribution/polars_ops_multiple_arguments/src/lib.rs => docs/development/contributing/code-style.md (85%) create mode 100644 docs/development/contributing/ide.md rename docs/development/{contributing.md => contributing/index.md} (99%) rename py-polars/tests/README.md => docs/development/contributing/test.md (87%) diff --git a/Cargo.toml b/Cargo.toml index 90480e5e8525..a32e5f0a7c9c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,7 +2,6 @@ resolver = "2" members = [ "crates/*", - "contribution/*", "examples/*", ] default-members = [ diff --git a/contribution/README.md b/contribution/README.md deleted file mode 100644 index e7ed037ae092..000000000000 --- a/contribution/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# Contribution guideline examples - -This subdirectory is intended to provide examples that guide contributors. - -Naming conventions for variables: - -```rust -let s: Series = ... -let ca: ChunkedArray = ... -let arr: ArrayRef = ... -let arr: PrimitiveArray = ... -let dtype: DataType = ... -let data_type: ArrowDataType = ... -``` - -# Visual Studio Code settings - -In case you use Visual Studio Code, the following settings are recommended -for rust-analyzer to detect all code: - -```json -{ - "rust-analyzer.cargo.features": "all", - "rust-analyzer.linkedProjects": ["py-polars/Cargo.toml"], -} -``` - -You can place this in `.vscode/settings.json` in the repository root. diff --git a/contribution/polars_ops_multiple_arguments/Cargo.toml b/contribution/polars_ops_multiple_arguments/Cargo.toml deleted file mode 100644 index 4cda3db2c267..000000000000 --- a/contribution/polars_ops_multiple_arguments/Cargo.toml +++ /dev/null @@ -1,8 +0,0 @@ -[package] -name = "polars_ops_multiple_arguments" -version = "0.1.0" -edition = "2021" - -[dependencies] -polars = { path = "../../crates/polars" } -polars-core = { path = "../../crates/polars-core" } diff --git a/docs/_build/snippets/under_construction.md b/docs/_build/snippets/under_construction.md index c4bb56a735af..9ac0d3fcc613 100644 --- a/docs/_build/snippets/under_construction.md +++ b/docs/_build/snippets/under_construction.md @@ -1,4 +1,4 @@ -!!! warning ":construction: Under Construction :construction: " +!!! warning ":construction: Under Construction :construction:" This section is still under development. Want to help out? Consider contributing and making a [pull request](https://github.com/pola-rs/polars) to our repository. Please read our [Contribution Guidelines](https://github.com/pola-rs/polars/blob/main/CONTRIBUTING.md) on how to proceed. diff --git a/.github/workflows/README.md b/docs/development/contributing/ci.md similarity index 89% rename from .github/workflows/README.md rename to docs/development/contributing/ci.md index 147a8e8dda93..b85330590092 100644 --- a/.github/workflows/README.md +++ b/docs/development/contributing/ci.md @@ -1,6 +1,6 @@ -# Continuous integration setup +# Continuous integration -Polars uses GitHub Actions as its continuous integration (CI) tool. The setup is reasonably complex, as far as CI setups go. This document explains some of the design choices. +Polars uses GitHub Actions as its continuous integration (CI) tool. The setup is reasonably complex, as far as CI setups go. This page explains some of the design choices. ## Goal @@ -40,6 +40,7 @@ However, since GitHub Actions does not allow sharing caches between feature bran Care must also be taken not to exceed the maximum cache space of 10Gb allotted to open source GitHub repositories. Hence we do not do any caching on feature branches - we always use the cache available from the main branch. This also avoids any extra time that would be required to store the cache. -# Releases +## Releases -The release jobs for Rust and Python get triggered when a new release is published. Release drafter is used to automatically draft these releases. Refer to the [contributing guide](/CONTRIBUTING.md#release-flow) for the full release process. +The release jobs for Rust and Python are triggered manually. +Refer to the [contributing guide](./index.md#release-flow) for the full release process. diff --git a/contribution/polars_ops_multiple_arguments/src/lib.rs b/docs/development/contributing/code-style.md similarity index 85% rename from contribution/polars_ops_multiple_arguments/src/lib.rs rename to docs/development/contributing/code-style.md index 7c4503f6b500..b5ce5b2fcd9d 100644 --- a/contribution/polars_ops_multiple_arguments/src/lib.rs +++ b/docs/development/contributing/code-style.md @@ -1,3 +1,29 @@ +# Code style + +This page contains some guidance on code style. + +!!! info + + Additional information will be added to this page later. + +## Rust + +### Naming conventions + +Naming conventions for variables: + +```rust +let s: Series = ... +let ca: ChunkedArray = ... +let arr: ArrayRef = ... +let arr: PrimitiveArray = ... +let dtype: DataType = ... +let data_type: ArrowDataType = ... +``` + +### Code example + +```rust use std::ops::Add; use polars::export::arrow::array::*; @@ -65,3 +91,4 @@ pub fn compute_expr_2_args(arg_1: &Series, arg_2: &Series) -> Series { compute_chunked_array_2_args(ca_1, ca_2).into_series() }) } +``` diff --git a/docs/development/contributing/ide.md b/docs/development/contributing/ide.md new file mode 100644 index 000000000000..5b9f13573b7f --- /dev/null +++ b/docs/development/contributing/ide.md @@ -0,0 +1,32 @@ +# IDE configuration + +Using an integrated development environments (IDE) and configuring it properly will help you work on Polars more effectively. +This page contains some recommendations for configuring popular IDEs. + +## Visual Studio Code + +The following extensions are recommended. + +### rust-analyzer + +If you work on the Rust code at all, you will need the [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) extension. This extension provides code completion for the Rust code. + +For it to work well for the Polars code base, add the following settings to your `.vscode/settings.json`: + +```json +{ + "rust-analyzer.cargo.features": "all", + "rust-analyzer.linkedProjects": ["py-polars/Cargo.toml"], +} +``` + +### Ruff + +The Ruff extension will help you conform to the formatting requirements of the Python code. +We use both the Ruff linter and formatter. + +## PyCharm / RustRover / CLion + +!!! info + + More information needed. diff --git a/docs/development/contributing.md b/docs/development/contributing/index.md similarity index 99% rename from docs/development/contributing.md rename to docs/development/contributing/index.md index 51fbeddb8bb1..a537a407b65d 100644 --- a/docs/development/contributing.md +++ b/docs/development/contributing/index.md @@ -2,7 +2,7 @@ render_macros: false --- -# Contributing +# Overview Thanks for taking the time to contribute! We appreciate all contributions, from reporting bugs to implementing new features. If you're unclear on how to proceed after reading this guide, please contact us on [Discord](https://discord.gg/4UfP5cfBE7). diff --git a/py-polars/tests/README.md b/docs/development/contributing/test.md similarity index 87% rename from py-polars/tests/README.md rename to docs/development/contributing/test.md index 8030f33ca280..cf102f0fdf5c 100644 --- a/py-polars/tests/README.md +++ b/docs/development/contributing/test.md @@ -1,17 +1,17 @@ -# Polars test suite +# Test suite -This folder contains the main Polars test suite. This document contains some information on the various components of the test suite, as well as guidelines for writing new tests. +!!! info -The test suite contains four main components, each confined to their own folder: unit tests, parametric tests, benchmark tests, and doctests. + Additional information on the Rust test suite will be added to this page later. -Note that this test suite is indirectly responsible for testing Rust Polars as well. The Rust test suite is kept small to reduce compilation times. A lot of the Rust functionality is tested here instead. +The `py-polars/tests` folder contains the main Polars test suite. +This page contains some information on the various components of the test suite, as well as guidelines for writing new tests. -## Table of contents +The test suite contains four main components, each confined to their own folder: unit tests, parametric tests, benchmark tests, and doctests. -- [Unit tests](#unit-tests) -- [Parametric tests](#parametric-tests) -- [Doctests](#doctests) -- [Benchmark tests](#benchmark-tests) +Note that this test suite is indirectly responsible for testing Rust Polars as well. +The Rust test suite is kept small to reduce compilation times. +A lot of the Rust functionality is tested here instead. ## Unit tests @@ -20,11 +20,13 @@ These tests are intended to make sure all Polars functionality works as intended ### Running unit tests -Run unit tests by running `make test` from the `py-polars` folder. This will compile the Rust bindings and then run the unit tests. +Run unit tests by running `make test` from the `py-polars` folder. +This will compile the Rust bindings and then run the unit tests. If you're working in the Python code only, you can avoid recompiling every time by simply running `pytest` instead. -By default, slow tests are skipped. Slow tests are marked as such using a [custom pytest marker](https://docs.pytest.org/en/latest/example/markers.html). +By default, slow tests are skipped. +Slow tests are marked as such using a [custom pytest marker](https://docs.pytest.org/en/latest/example/markers.html). If you wish to run slow tests, run `pytest -m slow`. Or run `pytest -m ""` to run _all_ tests, regardless of marker. @@ -103,7 +105,7 @@ The benchmark is somewhat cumbersome to run locally. You must first generate the Make sure to install a release build of Polars before running the benchmark to guarantee the best results. -Refer to the [benchmark workflow](/.github/workflows/benchmark.yml) for detailed steps. +Refer to the [benchmark workflow](https://github.com/pola-rs/polars/blob/main/.github/workflows/benchmark.yml) for detailed steps. ### Running other benchmark tests diff --git a/docs/index.md b/docs/index.md index 851c27082853..e0a670cbf928 100644 --- a/docs/index.md +++ b/docs/index.md @@ -60,7 +60,7 @@ Polars has a very active community with frequent releases (approximately weekly) ## Contributing -We appreciate all contributions, from reporting bugs to implementing new features. Read our [contributing guide](development/contributing.md) to learn more. +We appreciate all contributions, from reporting bugs to implementing new features. Read our [contributing guide](development/contributing/index.md) to learn more. ## License diff --git a/mkdocs.yml b/mkdocs.yml index 4c3f87b36862..526c5d05672a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -86,7 +86,12 @@ nav: - API reference: api/index.md - Development: - - development/contributing.md + - Contributing: + - development/contributing/index.md + - development/contributing/ide.md + - development/contributing/test.md + - development/contributing/ci.md + - development/contributing/code-style.md - development/versioning.md - Releases: