chore: import upstream snapshot with attribution

doc/source/data/contributing/contributing-guide.md

@@ -0,0 +1,62 @@
+# Contributing Guide
+
+If you want your changes to be reviewed and merged quickly, following a few key practices makes a big difference. Clear, focused, and well-structured contributions help reviewers understand your intent and ensure your improvements land smoothly.
+
+:::{seealso}
+This guide covers contributing to Ray Data in specific. For information on contributing to the Ray project in general, see the {ref}`general Ray contributing guide<getting-involved>`.
+:::
+
+## Find something to work on
+
+Start by solving a problem you encounter, like fixing a bug or adding a missing feature. If you're unsure where to start:
+* Browse the issue tracker for problems you understand.
+* Look for labels like ["good first issue"](https://github.com/ray-project/ray/issues?q=is%3Aissue%20state%3Aopen%20label%3Agood-first-issue%20label%3Adata) for approachable tasks.
+* [Join the Ray Slack](https://www.ray.io/join-slack) and post in #data-contributors.
+
+## Get early feedback
+
+If you’re adding a new public API or making a substantial refactor, **share your plan early**. Discussing changes before you invest a lot of work can save time and align your work with the project’s direction.
+
+You can open a draft PR, discuss on an Issue, or post in Slack for early feedback. It won’t affect acceptance and often improves the final design.
+
+## Write good tests
+
+Most changes to Ray Data require tests. For tips on how to write good tests, see {ref}`How to write tests <how-to-write-tests>`.
+
+## Write simple, clear code
+
+Ray Data values **readable, maintainable, and extendable** code over clever tricks. For guidance on how to write code that aligns with Ray Data's design taste, see [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/aposd2ndEdExtract.pdf).
+
+## Test your changes locally
+
+To test your changes locally, build [Ray from source](https://docs.ray.io/en/latest/ray-contribute/development.html). For Ray Data development, you typically only need the Python environment—you can skip the C++ build unless you’re also contributing to Ray Core.
+
+Before submitting a PR, run `pre-commit` to lint your changes and `pytest` to execute your tests.
+
+Note that the full Ray Data test suite can be heavy to run locally, start with tests directly related to your changes. For example, if you modified `map`, from `python/ray/data/tests` run: `pytest test_map.py`.
+
+
+## Open a pull request
+
+### Write a clear pull request description
+
+Explain **why the change exists and what it achieves**. Clear descriptions reduce back-and-forth and speed up reviews.
+
+Here's an example of a PR with a good description: [[Data] Refactor PhysicalOperator.completed to fix side effects ](https://github.com/ray-project/ray/pull/58915).
+
+### Keep pull requests small
+
+Review difficulty scales non-linearly with PR size.
+
+For fast reviews, do the following:
+* **Keep PRs under ~200 lines** of change when possible.
+* **Split large PRs** into multiple incremental PRs.
+* Avoid mixing refactors and new features in the same PR.
+
+Here's an example of a PR that keeps its scope small: [[Data] Support Non-String Items for ApproximateTopK Aggregator](https://github.com/ray-project/ray/pull/58659). While the broader effort focuses on optimizing preprocessors, this change was deliberately split out as a small, incremental PR, which made it much easier to review.
+
+### Make CI pass
+
+Ray's CI runs lint and a small set of tests first in the `buildkite/microcheck` check. Start by making that pass.
+
+Once it’s green, tag your reviewer. They can add the go label to trigger the full test suite.

doc/source/data/contributing/contributing.rst

@@ -0,0 +1,9 @@
+========================
+Contributing to Ray Data
+========================
+
+.. toctree::
+    :maxdepth: 2
+
+    contributing-guide
+    how-to-write-tests

doc/source/data/contributing/how-to-write-tests.md

@@ -0,0 +1,176 @@
+(how-to-write-tests)=
+# How to write tests
+
+:::{note}
+**Disclaimer**: There are no hard rules in software engineering. Use your judgment when applying these.
+:::
+
+Flaky or brittle tests (the kind that break when assumptions shift) slow development. Nobody likes getting stuck on a PR because a test failed for reasons unrelated to their change.
+
+This guide is a collection of practices to help you write tests that support the Ray Data project, not slow it down.
+
+## General good practices
+
+### Prefer unit tests over integration tests
+
+Unit tests give faster feedback and make it easier to pinpoint failures. They run in milliseconds, not seconds, and don’t depend on Ray clusters, external systems, or timing. This keeps the test suite fast, reliable, and easy to maintain.
+
+:::{note}
+Put unit tests in `python/ray/data/tests/unit`.
+:::
+
+### Use fixtures, skip try-finally
+
+Fixtures make tests cleaner, more reusable, and better isolated. They’re the right tool for setup and teardown, especially for things like `monkeypatch`.
+
+`try-finally` works, but fixtures make intent clearer and avoid boilerplate.
+
+**Original code**
+```python
+def test_dynamic_block_split(ray_start_regular_shared):
+    ctx = ray.data.context.DataContext.get_current()
+    original_target_max_block_size = ctx.target_max_block_size
+
+    ctx.target_max_block_size = 1
+    try: 
+        ...
+    finally:
+        ctx.target_max_block_size = original_target_max_block_size
+```
+
+**Better**
+```python
+def test_dynamic_block_split(ray_start_regular_shared, restore_data_context):
+    ctx = ray.data.context.DataContext.get_current()
+    target_max_block_size = ctx.target_max_block_size
+    ... # No need for try-finally
+```
+
+## Ray-specific practices
+
+### Don't assume Datasets produce outputs in a specific order
+
+Unless you set `preserve_order=True` in the `DataContext`, Ray Data doesn’t guarantee an output order. If your test relies on order without explicitly asking for it, you’re setting yourself up for brittle failures.
+
+**Original code**
+```python
+ds_dfs = []
+for path in os.listdir(out_path):
+    assert path.startswith("data_") and path.endswith(".parquet")
+    ds_dfs.append(pd.read_parquet(os.path.join(out_path, path)))
+
+ds_df = pd.concat(ds_dfs).reset_index(drop=True)
+df = pd.concat([df1, df2]).reset_index(drop=True)
+assert ds_df.equals(df)
+```
+
+**Better**
+```python
+from ray.data._internal.util import rows_same
+
+actual_data = pd.read_parquet(out_path)
+expected_data = pd.concat([df1, df2]
+assert rows_same(actual_data, expected_data)
+```
+
+:::{tip}
+Use the `ray.data._internal.util.rows_same` utility function to compare pandas DataFrames for equality while ignoring indices and order.
+:::
+
+### Prefer shared cluster fixtures
+
+Prefer shared cluster fixtures like `ray_start_regular_shared` over isolated cluster fixtures like `shutdown_only` and `ray_start_regular`.
+
+`shutdown_only` and `ray_start_regular` restart the Ray cluster after each test finishes. Starting and stopping Ray can take over a second — which sounds small, but across thousands of tests (plus parameterizations) it adds up fast.
+
+Only use isolated clusters when your test truly needs a fresh cluster.
+
+:::{note}
+There's an inherent tradeoff between isolation and speed here. For this specific case, choose to prioritize speed.
+:::
+
+**Original code**
+```python
+@pytest.mark.parametrize("concurrency", [-1, 1.5], ids=["negative", "float"])
+def test_invalid_concurrency_raises(shutdown_only, concurrency):
+    ds = ray.data.range(1)  # Each parametrization restarts the Ray cluster!
+    with pytest.raises(ValueError):
+        ds.map(lambda row: row, concurrency=concurrency)
+```
+
+**Better**
+```python
+@pytest.mark.parametrize("concurrency", [-1, 1.5], ids=["negative", "float"])
+def test_invalid_concurrency_raises(ray_start_regular_shared, concurrency):
+    ds = ray.data.range(1)  # Each parametrization reuses the same Ray cluster.
+    with pytest.raises(ValueError):
+        ds.map(lambda row: row, concurrency=concurrency)
+```
+
+### Avoid testing against repr outputs to validate specific data
+
+`repr` output isn’t part of any interface contract — it can change at any time. Besides, tests that assert against repr often hide the real intent: are you trying to check the data, or just how it happens to print? Be explicit about what you care about.
+
+
+
+**Original code**
+```python
+assert str(ds) == "Dataset(num_rows=6, schema={one: int64, two: string})", ds
+```
+
+**Better**
+```python
+assert ds.schema() == Schema(pa.schema({"one": pa.int64(), "two": pa.string()}))
+assert ds.count() == 6
+```
+
+### Avoid assumptions about the number or size of blocks
+
+Unless you’re testing an API like `repartition`, don’t lock your test to a specific number or size of blocks. Both can change depending on the implementation or the cluster config — and that’s usually fine.
+
+**Original code**
+
+```python
+ds = ray.data.read_parquet(paths + [txt_path], filesystem=fs)
+assert ds._plan.initial_num_blocks() == 2  # Where does 2 come from?
+assert rows_same(ds.to_pandas(), expected_data)
+```
+
+**Better**
+
+```python
+ds = ray.data.read_parquet(paths + [txt_path], filesystem=fs)
+# Assertion about number of blocks has been removed.
+assert rows_same(ds.to_pandas(), expected_data)
+```
+
+**Original code**
+```python
+ds2 = ds.repartition(5)
+assert ds2._plan.initial_num_blocks() == 5
+assert ds2._block_num_rows() == [10, 10, 0, 0, 0]  # Magic numbers?
+```
+
+**Better**
+```python
+ds2 = ds.repartition(5)
+assert sum(len(bundle.blocks) for bundle in ds.iter_internal_ref_bundles()) == 5
+# Assertion about the number of rows in each block has been removed.
+```
+
+### Avoid testing that the DAG looks a particular way
+
+The operators in the execution plan can shift over time as the implementation evolves. Unless you’re specifically testing optimization rules or working at the operator level, tests shouldn’t expect a particular DAG structure.
+
+**Original code**
+```python
+# Check that metadata fetch is included in stats.
+assert "FromArrow" in ds.stats()
+# Underlying implementation uses `FromArrow` operator
+assert ds._plan._logical_plan.dag.name == "FromArrow"
+```
+
+**Better**
+```python
+# (Assertions removed). 
+```