diff --git a/docs/content/about/releases.mdx b/docs/content/about/releases.mdx
index 22957f0d6f71e..a93c81884c95b 100644
--- a/docs/content/about/releases.mdx
+++ b/docs/content/about/releases.mdx
@@ -23,6 +23,12 @@ The "experimental" marker allows us to offer new APIs to users and rapidly itera
Experimental APIs may change or disappear within any release, but we try to avoid breaking them within minor releases if they have been around for a long time.
+### Preview APIs
+
+The "preview" marker allows us to offer APIs in early testing phase to users and rapidly iterate based on their feedback. Preview APIs are marked as such in the [API reference](/\_apidocs) and usually raise a when used.
+
+Preview APIs may change or disappear within any release and are not considered ready for production use.
+
### Superseded APIs
The "superseded" marker indicates that we recommend avoiding an API, usually because there's a preferred option that should be used instead.
diff --git a/docs/markdoc-component-documentation.md b/docs/markdoc-component-documentation.md
index 1a72e34045a79..434511d3feea6 100644
--- a/docs/markdoc-component-documentation.md
+++ b/docs/markdoc-component-documentation.md
@@ -280,6 +280,7 @@ We've also got a bunch of badges that you can use to indicate the level of suppo
There are the available badges:
- `{% experimental /%}` {% experimental /%}
+- `{% preview /%}` {% preview /%}
- `{% deprecated /%}` {% deprecated /%}
- `{% superseded /%}` {% superseded /%}
- `{% legacy /%}` {% legacy /%}
diff --git a/docs/next/components/markdoc/Badges.tsx b/docs/next/components/markdoc/Badges.tsx
index 35b9183e48e9d..ec29a6dcb4ed5 100644
--- a/docs/next/components/markdoc/Badges.tsx
+++ b/docs/next/components/markdoc/Badges.tsx
@@ -19,6 +19,14 @@ export const Experimental = () => {
);
};
+export const Preview = () => {
+ return (
+
diff --git a/docs/next/components/mdx/MDXComponents.tsx b/docs/next/components/mdx/MDXComponents.tsx
index 252e0a369930b..47bc9b5bbb850 100644
--- a/docs/next/components/mdx/MDXComponents.tsx
+++ b/docs/next/components/mdx/MDXComponents.tsx
@@ -429,6 +429,18 @@ const Experimental = () => {
);
};
+////////////////////////
+// Preview BADGE //
+////////////////////////
+
+const Preview = () => {
+ return (
+
+ (Preview)
+
+ );
+};
+
////////////////////////
// DEPRECATED BADGE //
////////////////////////
@@ -866,6 +878,7 @@ export default {
Experimental,
Deprecated,
Superseded,
+ Preview,
Legacy,
Icons,
ReferenceTable,
diff --git a/docs/next/markdoc/tags.js b/docs/next/markdoc/tags.js
index e926aa10880d8..220d17ebb541d 100644
--- a/docs/next/markdoc/tags.js
+++ b/docs/next/markdoc/tags.js
@@ -1,5 +1,5 @@
import {ArticleList, ArticleListItem} from '../components/markdoc/ArticleList';
-import {Badge, Experimental, Deprecated, Superseded, Legacy} from '../components/markdoc/Badges';
+import {Badge, Experimental, Preview, Deprecated, Superseded, Legacy} from '../components/markdoc/Badges';
import {Button, ButtonContainer} from '../components/markdoc/Button';
import {Note, Warning} from '../components/markdoc/Callouts';
import {Check, Cross} from '../components/markdoc/CheckCross';
@@ -80,6 +80,11 @@ export const experimental = {
selfClosing: true,
};
+export const preview = {
+ render: Preview,
+ selfClosing: true,
+};
+
export const deprecated = {
render: Deprecated,
selfClosing: true,
diff --git a/docs/next/styles/globals.css b/docs/next/styles/globals.css
index d94a9cc022bd2..d676c1897fb81 100644
--- a/docs/next/styles/globals.css
+++ b/docs/next/styles/globals.css
@@ -104,6 +104,11 @@ dt > a.reference.internal {
@apply inline-flex items-center px-3 py-0.5 rounded-full align-middle text-xs uppercase font-medium bg-sea-foam text-gable-green
}
+.preview-tag,
+.flag.preview {
+ @apply inline-flex items-center px-3 py-0.5 rounded-full align-middle text-xs uppercase font-medium bg-sea-foam text-gable-green
+}
+
.deprecated-tag {
@apply inline-flex items-center px-3 py-0.5 rounded-full align-middle text-xs uppercase font-medium bg-gray-300 text-gray-900
}
diff --git a/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/__init__.py b/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/__init__.py
index da1e164dcf171..150c3a8fc3752 100644
--- a/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/__init__.py
+++ b/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/__init__.py
@@ -6,11 +6,13 @@
get_deprecated_params,
get_experimental_info,
get_experimental_params,
+ get_preview_info,
get_superseded_info,
has_deprecated_params,
has_experimental_params,
is_deprecated,
is_experimental,
+ is_preview,
is_public,
is_superseded,
)
@@ -126,6 +128,9 @@ def process_docstring(
if is_superseded(obj):
inject_object_flag(obj, get_superseded_info(obj), lines)
+ if is_preview(obj):
+ inject_object_flag(obj, get_preview_info(obj), lines)
+
if has_deprecated_params(obj):
params = get_deprecated_params(obj)
for param, info in params.items():
diff --git a/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/docstring_flags.py b/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/docstring_flags.py
index f557cebc80967..f1d82e9db9fa9 100644
--- a/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/docstring_flags.py
+++ b/docs/sphinx/_ext/dagster-sphinx/dagster_sphinx/docstring_flags.py
@@ -3,7 +3,7 @@
import dagster._check as check
import docutils.nodes as nodes
-from dagster._annotations import DeprecatedInfo, ExperimentalInfo, SupersededInfo
+from dagster._annotations import DeprecatedInfo, ExperimentalInfo, PreviewInfo, SupersededInfo
from sphinx.util.docutils import SphinxDirective
@@ -15,7 +15,9 @@
def inject_object_flag(
- obj: object, info: Union[SupersededInfo, DeprecatedInfo, ExperimentalInfo], docstring: list[str]
+ obj: object,
+ info: Union[SupersededInfo, DeprecatedInfo, ExperimentalInfo, PreviewInfo],
+ docstring: list[str],
) -> None:
if isinstance(info, DeprecatedInfo):
additional_text = f" {info.additional_warn_text}." if info.additional_warn_text else ""
@@ -31,6 +33,13 @@ def inject_object_flag(
additional_text = f" {info.additional_warn_text}." if info.additional_warn_text else ""
flag_type = "superseded"
message = f"This API has been superseded and its usage is discouraged.\n{additional_text}"
+ elif isinstance(info, PreviewInfo):
+ additional_text = f" {info.additional_warn_text}." if info.additional_warn_text else ""
+ flag_type = "preview"
+ message = (
+ f"This API is currently in preview, and may have breaking changes in patch version releases. "
+ f"This API is not considered ready for production use.\n{additional_text}"
+ )
else:
check.failed(f"Unexpected info type {type(info)}")
for line in reversed([f".. flag:: {flag_type}", "", f" {message}", ""]):
diff --git a/docs/sphinx/sections/api/apidocs/utilities.rst b/docs/sphinx/sections/api/apidocs/utilities.rst
index c35645ae98013..86aadbd83ec38 100644
--- a/docs/sphinx/sections/api/apidocs/utilities.rst
+++ b/docs/sphinx/sections/api/apidocs/utilities.rst
@@ -15,6 +15,8 @@ Utilities
.. autoclass:: ExperimentalWarning
+.. autoclass:: dagster._utils.warnings.PreviewWarning
+
.. autofunction:: make_email_on_run_failure_sensor
.. currentmodule:: dagster._utils.forked_pdb