Consider migrating from nightly Rust toolchain to stable

[coderabbitai]

Issue Description

The project currently uses a pinned nightly Rust toolchain (nightly-2025-07-22) primarily due to the usage of the doc_cfg feature in documentation.

Current State

• rust-toolchain.toml pins to nightly channel
• docs/rust-doctest-dry-guide.md:486 uses #![feature(doc_cfg)] which is nightly-only

Potential Solutions

1. Remove or isolate the doc_cfg feature so it doesn't run under cargo test --doc on stable
2. Wrap the feature in conditional compilation to only use it when nightly is available
3. Document the requirement explicitly in README and rust-toolchain.toml if nightly is necessary

Benefits of Migration

• Lower maintenance overhead (stable releases have less churn)
• Better compatibility with downstream users
• More predictable build environment

Context

This issue was identified during PR review when adding llvm-tools-preview component for coverage testing.

Related:

• PR: Add coverage test target #58
• Comment: Add coverage test target #58 (comment)

[leynos]

@coderabbitai looking at the codebase, is this issue still relevant? If the issue has been fixed in the code, does the documentation reflect this?

If it is still relevant, please provide an assessment of the issue criticality (critical, high, medium or low), based on risk of the issue impacting the user and the anticipated blast radius.

Once a decision has been made, apply the appropriate label.

If the issue is documentation ONLY (i.e., no code changes needed), apply the documentation label in addition to the appropriate criticality label.

Please also provide an impact of the required changes.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if rust-toolchain.toml exists and what toolchain is configured
echo "=== Checking rust-toolchain.toml ==="
if [ -f "rust-toolchain.toml" ]; then
    cat rust-toolchain.toml
else
    echo "rust-toolchain.toml not found"
fi

echo -e "\n=== Checking for rust-toolchain file ==="
if [ -f "rust-toolchain" ]; then
    cat rust-toolchain
else
    echo "rust-toolchain file not found"
fi

echo -e "\n=== Checking docs/rust-doctest-dry-guide.md ==="
if [ -f "docs/rust-doctest-dry-guide.md" ]; then
    echo "File exists, checking for doc_cfg feature:"
    grep -n "doc_cfg" docs/rust-doctest-dry-guide.md || echo "No doc_cfg found"
    echo "Checking for #![feature lines:"
    grep -n "#!\[feature" docs/rust-doctest-dry-guide.md || echo "No #![feature lines found"
else
    echo "docs/rust-doctest-dry-guide.md not found"
fi

echo -e "\n=== Searching for nightly-only features across codebase ==="
rg -n "#!\[feature" --type=rs

Length of output: 689

---

🏁 Script executed:

#!/bin/bash
# Fix the regex and search for nightly-only features across codebase
echo "=== Searching for nightly-only features across codebase ==="
rg -n "#!\[feature" --type=rs

echo -e "\n=== Also search in all files for feature attributes ==="
rg -n "feature\(" 

echo -e "\n=== Check Cargo.toml files for any nightly dependencies ==="
fd -e toml -x cat {} \;

echo -e "\n=== Check if there are any other doc_cfg usages ==="
rg -n "doc_cfg"

Length of output: 7241

---

🏁 Script executed:

#!/bin/bash
# Let's properly search for feature attributes with correct escaping
echo "=== Searching for nightly-only features in Rust files ==="
rg -n '#!\[feature' --type=rs

echo -e "\n=== Check the specific lib.rs file that uses doc_cfg ==="
cat crates/comenqd/src/lib.rs | head -10

echo -e "\n=== Search for any other nightly-specific features ==="
rg -n 'nightly' .

echo -e "\n=== Check if there are any build.rs files that might need nightly ==="
fd -n build.rs -x cat {} \;

Length of output: 1131

---

🏁 Script executed:

#!/bin/bash
# Fix the fd command and search for build.rs files
echo "=== Check if there are any build.rs files that might need nightly ==="
fd build.rs -x cat {} \;

echo -e "\n=== Use literal search for feature attributes ==="
rg -F '#![feature' --type=rs

echo -e "\n=== Check what's in the docs file more thoroughly ==="
head -20 docs/rust-doctest-dry-guide.md

echo -e "\n=== Check if the project builds on stable by looking at CI files ==="
fd -e yml -e yaml | head -5 | xargs cat

echo -e "\n=== Look at README to see if nightly requirement is documented ==="
if [ -f "README.md" ]; then
    grep -i -A5 -B5 "nightly\|toolchain\|rust" README.md || echo "No mentions of nightly/toolchain found in README"
else
    echo "No README.md found"
fi

Length of output: 2009

---

🏁 Script executed:

#!/bin/bash
# Apply the correct label to the GitHub issue based on assessment
echo "=== Applying labels to the issue ==="
gh issue edit 62 --add-label "medium"

echo -e "\n=== Also check if there are any GitHub Actions workflows ==="
if [ -d ".github/workflows" ]; then
    echo "GitHub Actions workflows found:"
    ls .github/workflows/
    echo -e "\n=== Content of CI workflows ==="
    fd -e yml -e yaml .github/workflows -x cat {} \;
else
    echo "No .github/workflows directory found"
fi

echo -e "\n=== Check the actual content of rust files to understand usage ==="
find . -name "*.rs" -type f | head -3 | xargs head -5

Length of output: 1382

---

🏁 Script executed:

#!/bin/bash
# Check the GitHub Actions CI workflows to see if they use nightly or stable
echo "=== Checking CI workflows ==="
fd . .github/workflows -x cat {} \;

echo -e "\n=== Final check - let's see if there are any actual feature gates in use ==="
# Search for feature attributes without regex issues
grep -r "#!\[feature" . --include="*.rs" || echo "No #![feature found in .rs files"

echo -e "\n=== Check what happens if we try to build with stable toolchain ==="
echo "Current toolchain configuration shows nightly-2025-07-22"
echo "The main blocker appears to be the doc_cfg feature usage"

Length of output: 3346

---

@leynos Yes, this issue is still highly relevant! Based on my analysis of the current codebase:

Current State

The project still uses nightly Rust toolchain (nightly-2025-07-22) as configured in rust-toolchain.toml. The dependency on nightly remains due to:

1. docs/rust-doctest-dry-guide.md contains #![feature(doc_cfg)] on line 486
2. crates/comenqd/src/lib.rs uses #![cfg_attr(docsrs, feature(doc_cfg))]

Interestingly, the CI workflow in .github/workflows/release.yml uses stable Rust for releases, which suggests the project might already be compatible with stable for builds, but the nightly toolchain is maintained for documentation features.

Issue Criticality Assessment: MEDIUM

Risk factors:

• User Impact: Moderate - forces all contributors to use nightly Rust, creating friction for new contributors
• Maintenance Overhead: Regular nightly updates needed, potential breakage from nightly changes
• Compatibility: Downstream users may face toolchain conflicts

Mitigating factors:

• Project already builds with stable in CI release workflow
• The doc_cfg usage is conditional and primarily for documentation enhancement
• Core functionality doesn't depend on nightly features

Impact of Required Changes

The migration would require:

1. Code changes: Minimal - only need to handle the conditional doc_cfg feature in crates/comenqd/src/lib.rs
2. Documentation updates: Remove or conditionally compile the #![feature(doc_cfg)] in the doctest guide
3. Toolchain update: Change rust-toolchain.toml from nightly-2025-07-22 to stable

The impact is low to moderate since the project already demonstrates stable compatibility in CI builds.

I've applied the medium criticality label to the issue. The migration would benefit the project by reducing maintenance overhead and improving contributor onboarding while having minimal technical complexity.