docs: adds project status page (#37)

Author: claymcleod

.vitepress/config.mts

@@ -30,6 +30,7 @@ export default defineConfig({
         text: "Getting Started",
         items: [
           { text: "Overview", link: "/overview", docFooterText: "Getting Started > Overview" },
+          { text: "Project Status", link: "/project-status", docFooterText: "Getting Started > Project Status" },
           { text: "Installation", link: "/installation", docFooterText: "Getting Started > Installation" },
           { text: "Guided Tour", link: "/guided-tour", docFooterText: "Getting Started > Guided Tour" },
         ],

overview.md

@@ -1,6 +1,6 @@
 ![Sprocket Repository Header](/public/repo-header.png)
 
-**Sprocket** is an bioinformatics workflow execution engine built on top of the
+**Sprocket** is a bioinformatics workflow execution engine built on top of the
 [Workflow Description Language](https://openwdl.org). The project has multiple
 high-level goals, including to:
 
@@ -24,15 +24,6 @@ code that drives Sprocket is split across the [`wdl`] family of crates, the
 ([source](https://github.com/stjude-rust-labs/sprocket-vscode)), and the
 [Neovim plugin] ([source](https://github.com/stjude-rust-labs/sprocket.nvim)).
 
-::: tip Note
-**Sprocket** is currently an alpha-phase project. To that end,
-this page serves the purpose of describing what we hope Sprocket _will_ become
-rather than what it actually is today. If you're using Sprocket, we encourage
-you to follow the project on
-[GitHub](https://github.com/stjude-rust-labs/sprocket) to stay up to date on
-progress.
-:::
-
 ## Project goals
 
 ### High-performance workflow execution engine
@@ -58,7 +49,7 @@ carrying them out in an independent manner.
 
 Collectively, we consider the combination of an orchestration engine with one or
 more configured execution runtimes to comprise an **execution engine**. We
-envision the orchestration engine being provided by Sprocket alongside two
+envision the orchestration engine being provided by Sprocket alongside three
 official execution runtimes: (a) a local, Docker-based runtime, (b) a Task
 Execution Service ([TES]) based runtime, and (c) a flexible "generic" runtime
 that can be used to configure execution within HPC clusters. Beyond that, we
@@ -73,7 +64,7 @@ the project.
 
 A suite of development tools are included alongside the execution engine. We
 believe that, when you _do_ need to dust off your code editor and write an
-analysis workflow, that activity should as enjoyable as it can be. Supporting
+analysis workflow, that activity should be as enjoyable as it can be. Supporting
 tools, such as
 [linters](https://github.com/stjude-rust-labs/wdl/tree/main/wdl-lint),
 [formatters](https://github.com/stjude-rust-labs/wdl/tree/main/wdl-format),

project-status.md

@@ -0,0 +1,60 @@
+# Project Status
+
+Sprocket remains a pre-1.0 project, and as such, any part of its interface is
+technically subject to change between releases. In practice, however, the project
+has matured to the point where the command-line interface for most established
+commands (i.e., those not under the `dev` subcommand namespace) is relatively
+settled. We make a conscious effort not to alter the command interface unless we
+believe it is strictly necessary.
+
+## Stability across the project
+
+Not all areas of Sprocket are equally stable. The following gives a rough sense
+of what to expect.
+
+- **Established commands** (e.g., `run`, `check`, `lint`, `format`, `inputs`).
+  These are the most stable parts of the project. Changes to their interfaces are
+  infrequent and made only when we believe they meaningfully improve the user
+  experience.
+- **Configuration** (i.e., `Sprocket.toml`). This area is expected to undergo
+  significant changes over the next several versions as we refine how backends,
+  storage, and other options are configured. If you maintain configuration files
+  across environments, keep an eye on the changelog when upgrading.
+- **Experimental commands** (i.e., those under the `dev` subcommand namespace).
+  These commands are under active development, and their interfaces may change
+  substantially—or be removed entirely—between releases.
+
+Because Sprocket is still pre-1.0, we do not currently provide advance deprecation
+notices before breaking backwards compatibility for command interfaces. That said, we
+document each change so you know what to expect in each upgrade, as described
+below. In this way, we believe that you can depend on Sprocket in your
+workflows, even before the v1 release.
+
+## Release cadence
+
+Sprocket follows a **three-week release cycle**, with new versions shipping on
+every third Wednesday. You can track upcoming and past releases on the
+[GitHub releases page](https://github.com/stjude-rust-labs/sprocket/releases).
+
+## Upgrading between versions
+
+We rigorously document all changes, including breaking ones, in the CHANGELOGs for
+both [Sprocket](https://github.com/stjude-rust-labs/sprocket/blob/main/CHANGELOG.md)
+and its [associated crates](https://github.com/stjude-rust-labs/sprocket/tree/main/crates).
+All of this is surfaced in the
+[release notes](https://github.com/stjude-rust-labs/sprocket/releases), so you
+can easily scan for things that affect your use of Sprocket. When upgrading, run
+through the release notes for each version you are jumping across and you should
+be set.
+
+## Getting help
+
+If you run into trouble or have questions about a change, there are a few places
+to reach out.
+
+- **[OpenWDL Slack](https://join.slack.com/t/openwdl/shared_invite/zt-ctmj4mhf-cFBNxIiZYs6SY9HgM9UAVw)**—the
+  best place for general questions and conversation about Sprocket and WDL.
+- **[GitHub Issues](https://github.com/stjude-rust-labs/sprocket/issues)**—for
+  reporting bugs or problems you encounter.
+- **[GitHub Discussions](https://github.com/stjude-rust-labs/sprocket/discussions)**—for
+  broader questions, ideas, and everything else.