OPEN SOURCE / CONTRIBUTING

Make the safe path easier.

DATADOC is useful when its decisions are explainable to data scientists and maintainers. Contributions should favor clear contracts, small changes, and tests that prove no leakage.

Open GitHub ↗

Principles

Train-only state

Any median, vocabulary, clipping bound, scaler, or selection decision belongs in fit, never in transform.

Explain decisions

Findings and operations need a rationale that a reviewer can read without opening implementation internals.

Keep extras optional

Core profiling and transformation must work offline without AI, UI, or scikit-learn.

Transformation contract

A new transformation should fit the project lifecycle. This example is intentionally small; production code should also define its schema and serialization behavior.

Pythontrain-only plugin shape
import polars as pl

class CenterAmount:
    name = "center_amount"

    def analyze(self, df, context):
        return {"code": "CUSTOM_FINDING", "message": "Explain the finding"}

    def fit(self, train_df, context):
        return {"center": train_df["amount"].median()}

    def transform(self, df, fitted_state, context):
        center = fitted_state["center"]
        return df.with_columns(
            (pl.col("amount") - center).alias("amount_centered")
        )

    def validate(self, input_df, output_df, fitted_state):
        return {"valid": "amount_centered" in output_df.columns}

Do not add arbitrary code execution.

AI may suggest a constrained operation, but registered code and deterministic validation must control what runs.

Tests you should add

Test	Question it answers
Unit	Does the transformation handle nulls, empty data, binary values, and invalid dates?
Leakage	Can validation values change medians, vocabularies, bounds, or feature selection?
Round trip	Does save/load produce the same schema and values?
CLI	Do paths, extensions, and error messages work from a clean command?
UI	Can two sessions remain independent and do invalid orders fail?

Terminalbefore opening a PR
python -m pytest -q
python -m ruff check datadoc tests
python -m ruff format --check datadoc tests
python -m compileall -q datadoc

Pull request workflow

Fork the repository and create a focused branch.
Explain the user problem and the behavior change.
Update docs and examples when a public command changes.
Add tests before asking for review.
Run the local checks and describe any known boundaries.
Keep generated datasets, secrets, build directories, and local artifacts out of the commit.

Gitsmall, reviewable change
git switch -c feat/safer-datetime-transform
git add datadoc tests docs
git commit -m "feat: make datetime transform safer"
git push -u origin feat/safer-datetime-transform