Best practices

This page summarizes recommended best practices when developing and operating workloads with STACKIT Notebooks. Following these guidelines helps ensure maintainability, reproducibility, collaboration, and secure operation.

Development workflow

When working interactively, a structured workflow is essential. We recommend using Git for all code and notebooks:

• Store notebooks (.ipynb) and related Python modules in a Git repository.
• Use feature branches and pull requests for collaboration and review.
• Avoid keeping critical logic only inside running notebook servers.

Versioning notebooks properly

Notebooks are JSON files and can become difficult to review if not handled properly.

• Commit notebooks without running outputs
  Clear outputs before committing (for example through pre-commit hooks). This reduces merge conflicts and repository size.

• Keep business logic outside notebooks
  Move reusable logic into .py modules. Import those modules into the notebook. This makes testing and code review significantly easier.

• Use tools like nbdime
  Improves notebook diffs and merge handling.

Installing additional packages

Notebooks often require additional Python dependencies. The following tips enforce reproducibility and help avoid environment drift.

• Avoid permanent pip install commands inside notebooks
  Installing packages ad-hoc leads to non-reproducible environments. Restarting kernels may remove dynamically installed packages.

• Installing packages during runtime is acceptable for experiments only
  Commands like !pip install package-name are suitable for quick prototyping in DEV. Not suitable for production or shared environments.

• Best practice: Use custom profiles
  If you have special requirements regarding the runtime you want to use in STACKIT Notebooks, ask the Support to provide an additional profile which fits your needs.