Prepare 0.8.0 release docs and tests

Author: pasunboneleve

AGENTS.md

@@ -21,6 +21,10 @@ without hard-coding knowledge of any one repository.
 - Do not use `sleep` to resolve races. Races must be resolved with
   deterministic logic, explicit readiness signals, or ordered state
   transitions.
+- When tests must mutate process-global state such as environment
+  variables, isolate the unsafe operation in a small helper, serialize
+  access with a lock, and document the safety rationale instead of
+  scattering raw unsafe calls through test bodies.
 - Run quality gates for code changes: `cargo fmt`, `cargo test`,
   `cargo clippy --all-targets --all-features -- -D warnings`.
 

CHANGELOG.md

@@ -4,23 +4,38 @@ All notable changes to `devloop` will be recorded in this file.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-04-08
+
 ### Added
 - Added a configurable watcher backend with non-breaking `native`
   default behavior plus a `poll` fallback mode for environments where
   native filesystem notifications are unreliable.
-- Added a Rust repeated-edit watch flake smoke test that runs under
-  `cargo test` and therefore in GitHub Actions alongside the existing
-  runtime smoke test.
+- Added a Rust repeated-edit watch flake smoke test that can be run
+  locally with `DEVLOOP_RUN_WATCH_FLAKE_SMOKE=1 cargo test --test
+  watch_flake_smoke -- --nocapture`.
+- Added explicit trailing-slash syntax for literal directory watch
+  targets, for example `content/`, so recursive directory intent is
+  preserved even when the directory does not yet exist at startup.
+- Added a development guide under [`docs/development.md`](docs/development.md)
+  and exposed it in the CLI as `devloop docs development`.
 
 ### Changed
 - `devloop` now derives concrete watch targets from configured watch
   patterns and asks the backend to watch only those files or
   directories instead of always watching the whole repository root.
+- The watch flake smoke test is now opt-in instead of running during
+  every default `cargo test` or CI run. The existing runtime smoke test
+  remains in CI.
 
 ### Fixed
 - Native watch registration now resolves file and directory targets at
   runtime, so startup no longer depends on those paths already existing
   when config is parsed.
+- Fixed a real watch flake where the debounce batch could be dropped if
+  another `tokio::select!` branch won the race while filesystem events
+  were already buffered.
+- Test-only environment mutation now lives behind locked helpers with
+  documented safety rationale instead of scattered raw unsafe blocks.
 
 ## [0.7.0] - 2026-03-27
 

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "devloop"
-version = "0.7.0"
+version = "0.8.0"
 edition = "2024"
 
 [dependencies]

Cargo.toml

@@ -100,6 +100,7 @@ Built-in reference docs are also available from the CLI:
 ```bash
 devloop docs config
 devloop docs behavior
+devloop docs development
 devloop docs security
 ```
 
@@ -186,6 +187,9 @@ For the runtime behavior reference, see
 For the full configuration reference, see
 [`docs/configuration.md`](docs/configuration.md).
 
+For local contributor workflow details, including the opt-in watch
+flake smoke test, see [`docs/development.md`](docs/development.md).
+
 For the external-event trust model and push-versus-polling tradeoffs,
 see [`docs/security.md`](docs/security.md).
 

README.md

@@ -2,6 +2,7 @@
 
 - [Behavior Reference](behavior.md)
 - [Configuration Reference](configuration.md)
+- [Development Guide](development.md)
 - [Security Notes](security.md)
 
 This directory holds detailed reference material for `devloop`.

docs/README.md

@@ -60,6 +60,9 @@ watch-group patterns and watches only those files or directories.
 - The default backend uses native filesystem notifications. A polling
   backend can be selected in config as a fallback for environments
   where native events are unreliable.
+- Literal file targets are watched as narrowly as the backend allows.
+  Use a trailing `/` in the config when you mean an explicit directory
+  target that should be watched recursively.
 
 If multiple watch groups map to the same workflow, their matched paths
 are merged for that workflow run.

docs/behavior.md

@@ -56,21 +56,25 @@ bind = "127.0.0.1:0"
 Watch groups map file patterns to workflows.
 
 ```toml
-[watch.rust]
-paths = ["src/**/*.rs", "Cargo.toml"]
-workflow = "rust"
+[watch.content]
+paths = ["content/", "templates/**/*.html"]
+workflow = "content"
 ```
 
 - Table name: the watch-group name.
 - `paths`: glob patterns evaluated relative to `root`.
   Use a trailing `/` for a literal directory target that should be
-  watched recursively even before it exists.
+  watched recursively, including when the directory may not exist yet
+  at startup. Without the trailing slash, a literal path is treated as
+  a file target.
 - `workflow`: workflow to run when a matching file changes. If omitted,
   the watch-group name is used as the workflow name.
 
 `devloop` derives concrete watch targets from these patterns and asks
 the backend to watch only those literal files or directories instead of
-always watching the whole repository root recursively.
+always watching the whole repository root recursively. `native` remains
+the default backend; `poll` exists as a fallback for environments where
+filesystem notifications are unreliable.
 
 ## Processes
 

docs/configuration.md

@@ -0,0 +1,46 @@
+# Development Guide
+
+This guide covers local development workflows for `devloop` itself.
+
+## Quality gates
+
+Run the standard checks before committing:
+
+```bash
+cargo fmt
+cargo test
+cargo clippy --all-targets --all-features -- -D warnings
+./scripts/ci-smoke.sh
+```
+
+`./scripts/ci-smoke.sh` is the fast runtime smoke test used in CI. It
+checks that `devloop run` can start, begin watching, react to one file
+change, and shut down cleanly.
+
+## Opt-in watch flake smoke
+
+The repeated-edit watch flake smoke test is intentionally opt-in. It is
+useful when changing watch registration, debounce logic, or event
+delivery, but it is slower and more environment-sensitive than the
+standard test suite.
+
+Run it locally with:
+
+```bash
+DEVLOOP_RUN_WATCH_FLAKE_SMOKE=1 cargo test --test watch_flake_smoke -- --nocapture
+```
+
+Without that environment variable, the test exits early so normal
+`cargo test` and CI runs stay fast.
+
+## Test policy
+
+When a test must mutate process-global state such as environment
+variables:
+
+- serialize access with a test-local lock
+- keep `unsafe` in a narrow helper
+- document the safety rationale at the helper
+
+Do not scatter raw `unsafe { std::env::set_var(...) }` calls across test
+bodies.

docs/development.md

@@ -62,6 +62,7 @@ enum Command {
 enum DocsTopic {
     Config,
     Behavior,
+    Development,
     Security,
 }
 
@@ -151,6 +152,7 @@ fn docs_text(topic: DocsTopic) -> &'static str {
     match topic {
         DocsTopic::Config => include_str!("../docs/configuration.md"),
         DocsTopic::Behavior => include_str!("../docs/behavior.md"),
+        DocsTopic::Development => include_str!("../docs/development.md"),
         DocsTopic::Security => include_str!("../docs/security.md"),
     }
 }
@@ -345,32 +347,69 @@ mod tests {
         format_output_prefix, normalize_internal_log_label, normalize_source_label,
     };
     use clap::Parser;
-    use std::sync::{Mutex, OnceLock};
+    use std::ffi::OsString;
+    use std::sync::{Mutex, MutexGuard, OnceLock};
 
     fn rust_log_lock() -> &'static Mutex<()> {
         static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
         LOCK.get_or_init(|| Mutex::new(()))
     }
 
-    #[test]
-    fn default_rust_log_uses_info_when_unset() {
-        let _guard = rust_log_lock().lock().expect("lock RUST_LOG test mutex");
+    struct RustLogGuard {
+        _lock: MutexGuard<'static, ()>,
+        original: Option<OsString>,
+    }
+
+    impl RustLogGuard {
+        fn set(value: Option<&str>) -> Self {
+            let lock = rust_log_lock().lock().expect("lock RUST_LOG test mutex");
+            let original = std::env::var_os("RUST_LOG");
+            match value {
+                Some(value) => set_test_env_var("RUST_LOG", value),
+                None => remove_test_env_var("RUST_LOG"),
+            }
+            Self {
+                _lock: lock,
+                original,
+            }
+        }
+    }
+
+    impl Drop for RustLogGuard {
+        fn drop(&mut self) {
+            match &self.original {
+                Some(value) => set_test_env_var("RUST_LOG", value),
+                None => remove_test_env_var("RUST_LOG"),
+            }
+        }
+    }
+
+    fn set_test_env_var(key: &str, value: impl AsRef<std::ffi::OsStr>) {
+        // SAFETY: tests serialize all RUST_LOG mutation through `rust_log_lock`,
+        // so no concurrent test can observe partially updated process-global state.
         unsafe {
-            std::env::remove_var("RUST_LOG");
+            std::env::set_var(key, value);
         }
+    }
+
+    fn remove_test_env_var(key: &str) {
+        // SAFETY: tests serialize all RUST_LOG mutation through `rust_log_lock`,
+        // so removing the variable cannot race with other tests here.
+        unsafe {
+            std::env::remove_var(key);
+        }
+    }
+
+    #[test]
+    fn default_rust_log_uses_info_when_unset() {
+        let _guard = RustLogGuard::set(None);
         assert_eq!(default_rust_log(), "info");
     }
 
     #[test]
     fn default_rust_log_respects_environment_override() {
-        let _guard = rust_log_lock().lock().expect("lock RUST_LOG test mutex");
-        unsafe {
-            std::env::set_var("RUST_LOG", "debug,devloop=trace");
-        }
+        let _guard = RustLogGuard::set(Some("debug,devloop=trace"));
         assert_eq!(default_rust_log(), "debug,devloop=trace");
-        unsafe {
-            std::env::remove_var("RUST_LOG");
-        }
     }
 
     #[test]
@@ -418,6 +457,14 @@ mod tests {
         assert!(rendered.contains("startup_workflows"));
     }
 
+    #[test]
+    fn docs_text_uses_embedded_development_reference() {
+        let rendered = docs_text(DocsTopic::Development);
+
+        assert!(rendered.starts_with("# Development Guide"));
+        assert!(rendered.contains("DEVLOOP_RUN_WATCH_FLAKE_SMOKE"));
+    }
+
     #[test]
     fn rendered_docs_drop_markdown_heading_markers() {
         let rendered = render_docs_text(DocsTopic::Config);
@@ -460,4 +507,14 @@ mod tests {
             _ => panic!("expected docs subcommand"),
         }
     }
+
+    #[test]
+    fn cli_parses_development_docs_subcommand() {
+        let cli = Cli::try_parse_from(["devloop", "docs", "development"]).expect("parse cli");
+
+        match cli.command {
+            super::Command::Docs { topic } => assert!(matches!(topic, DocsTopic::Development)),
+            _ => panic!("expected docs subcommand"),
+        }
+    }
 }