Add developer guide, streamline PR template, AI reviewers

[sbryngelson]

User description

PR Type

Documentation, Enhancement

---

Description

• Add comprehensive developer guide with coding standards, architecture overview, and how-to guides

• Streamline PR template and contributing docs; consolidate AI reviewer configurations

• Add documentation linting tool to verify file path references in docs

• Update precheck script to include doc reference validation as 5th check

---

Diagram Walkthrough

flowchart LR
  A["Developer Guide<br/>contributing.md"] --> B["AI Reviewers<br/>Copilot/CodeRabbit/CodeAnt"]
  A --> C["PR Template"]
  A --> D["Coding Standards<br/>Hard Rules + Soft Guidelines"]
  A --> E["How-To Guides<br/>10 step-by-step recipes"]
  A --> F["Common Pitfalls<br/>Array bounds, precision, MPI, GPU"]
  G["lint_docs.py"] --> H["Precheck Step 5<br/>Validate doc references"]
  I["Consolidated AI Configs<br/>.coderabbit.yaml<br/>.codeant/configuration.json<br/>.pr_agent.toml"] --> B

Loading

File Walkthrough

	Relevant files
Enhancement	2 files lint_docs.py New tool to validate documentation file references              +54/-0    precheck.sh Add doc reference check as 5th precheck step                          +12/-4
Configuration changes	3 files configuration.json New CodeAnt AI reviewer configuration file                              +14/-0    .coderabbit.yaml New CodeRabbit AI reviewer configuration with path instructions +26/-0    .pr_agent.toml Update PR Agent config to reference canonical documentation files +12/-1
Documentation	6 files CONTRIBUTING.md Slim to pointer to canonical developer guide                          +10/-108 copilot-instructions.md Consolidate AI reviewer instructions with references to canonical docs +34/-58  pull_request_template.md Streamline PR template with fewer checkboxes and collapsible GPU section +18/-44  case.md Fix file path references to src/common/ hardcoded IC files +3/-3      contributing.md Add comprehensive 715-line developer guide with standards, pitfalls, and how-tos +715/-0  readme.md Add Development section linking to contributing guide        +4/-0

---

---

CodeAnt-AI Description

Add a canonical developer guide, AI reviewer configs, and a doc reference checker

What Changed

• A comprehensive developer guide (docs/documentation/contributing.md) is added and linked from the repository README and simplified CONTRIBUTING.md so contributors have a single, authoritative source for coding standards, workflows, GPU rules, testing, and CI expectations.
• PR template was simplified and now points reviewers and contributors to the developer guide; GPU checklist remains available as a collapsible section.
• AI reviewer configurations (.coderabbit.yaml, .codeant/configuration.json, .pr_agent.toml) were added/updated so automated reviewers prioritize the new guide, GPU macro API, and concrete review priorities (correctness, precision, MPI, GPU memory).
• A new doc reference linter (toolchain/mfc/lint_docs.py) and a precheck hook update run that linter during pre-push checks, causing pushes to fail if markdown references point to missing files.
• Many documentation files and examples were reorganized/updated to reference the new guide and to correct path references in docs (e.g., moving examples from src/pre_process/include to src/common/include where applicable).

Impact

✅ Clearer contributor onboarding and expectations
✅ Fewer broken documentation links detected before push
✅ More focused AI/code-review feedback on correctness and GPU/MPI pitfalls

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

Summary by CodeRabbit

• Documentation

  • Added a comprehensive developer/contributing guide and linked it from the docs.
  • Condensed the CONTRIBUTING quick-reference and updated PR template and AI code-review guidance.
  • Fixed several doc file path references.

• Tests & Tooling

  • Added a documentation reference validation check to precheck.

• Chores

  • Added editor/review configuration files to standardize review and editor integrations.

[codeant-ai]

CodeAnt AI is reviewing your PR.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[cursor]

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on March 8.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[coderabbitai]

Warning

Ignoring CodeRabbit configuration file changes. For security, only the configuration from the base branch is applied for open source repositories.

📝 Walkthrough

Walkthrough

Adds code-review/editor integration configs, rewrites GitHub contributor/Copilot/PR templates, adds a full contributing guide and docs updates, and integrates a new documentation reference linter into the precheck pipeline with an accompanying Python script.

Changes

Cohort / File(s)	Summary
Review & Editor Config .codeant/configuration.json, .coderabbit.yaml	New config files defining review/include/exclude globs and per-path editor/review guidelines and knowledge_base entries for code-guidance.
GitHub Contribution & PR Templates .github/CONTRIBUTING.md, .github/pull_request_template.md, .github/copilot-instructions.md	Major content rewrite: CONTRIBUTING shortened to a Quick Reference, PR template simplified, and Copilot instructions converted to an AI-focused code-review guide with new review priorities and PR-pattern triggers.
PR Agent Config .pr_agent.toml	Extended pr_reviewer instructions with a prioritized correctness checklist; enabled commitable code suggestions and apply-suggestions checkbox keys.
Documentation docs/documentation/contributing.md, docs/documentation/readme.md, docs/documentation/case.md	Adds a comprehensive contributing/developer guide and readme Development link; updates example file paths from src/pre_process/include/* to src/common/include/*.
Precheck & Doc Linting toolchain/bootstrap/precheck.sh, toolchain/mfc/lint_docs.py	Precheck script now runs a new doc-reference validation step (invokes toolchain/mfc/lint_docs.py); new Python script scans doc files for backtick-wrapped repo-relative paths and reports missing references.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Precheck as "precheck.sh"
  participant Linter as "toolchain/mfc/lint_docs.py"
  participant RepoFS as "Repository FS"
  participant CI as "CI / User"

  CI->>Precheck: run precheck
  Precheck->>Precheck: run formatting, spell, lint steps (1-4)
  Precheck->>Linter: execute doc reference check (step 5)
  Linter->>RepoFS: read doc files & resolve backtick paths
  RepoFS-->>Linter: return file existence results
  Linter-->>Precheck: report missing references (errors) or success
  Precheck->>CI: exit with status (fail if linter found issues)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Add CI lint gate and local precheck command #1122: Modifies the local precheck workflow — related to adding/running the doc-reference check and lint_docs.py.
• Three new examples cases #1060: Adds/updates hardcoded IC files under src/common/include, matching doc path updates in this PR.

Poem

🐇 I hopped through docs and paths so neat,
I checked each backtick, no link to cheat,
Guidelines trimmed, configs in tune,
Precheck hums beneath the moon,
Hooray — clean docs and workflows complete!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly captures the three main changes: adding a developer guide, streamlining the PR template, and configuring AI reviewers.
Description check	✅ Passed	The PR description is comprehensive with Type of change listed (Documentation, Enhancement), detailed summary of changes, a mermaid diagram, file walkthrough table, and clear impact statement; it substantially exceeds the template requirements.
Linked Issues check	✅ Passed	The PR description clearly links changes to PR #1134 and explains the coherent purpose of all modifications without explicitly requiring a separate issue reference.
Out of Scope Changes check	✅ Passed	All changes are within scope: documentation updates, configuration files, and tooling enhancements directly support the stated objective of adding a developer guide and streamlining review processes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

toolchain/bootstrap/precheck.sh (1)

130-137: Output handling is inconsistent with other precheck steps.

Steps 1–4 suppress command output (> /dev/null 2>&1) and tell the user to re-run for details, but step 5 lets lint_docs.py output flow to the terminal (2>&1 without > /dev/null). Meanwhile, the error message on Line 135 still says "Run … for details," which is redundant since the output was already shown.

Either suppress the output to match other steps, or drop the "Run … for details" hint from the error message.

Option A: Suppress output (consistent with other steps)

-if python3 toolchain/mfc/lint_docs.py 2>&1; then
+if python3 toolchain/mfc/lint_docs.py > /dev/null 2>&1; then

Option B: Keep inline output, simplify error message

-    error "Doc reference check failed. Run$MAGENTA python3 toolchain/mfc/lint_docs.py$COLOR_RESET for details."
+    error "Doc reference check failed (see output above)."

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Possible Issue The doc scanning logic may miss valid references or report false positives due to restrictive matching (only backtick-wrapped paths under a fixed set of root dirs) and simplistic skipping/stripping rules. Also, reading files without specifying encoding can break on non-UTF8 environments, and the error message formatting is inconsistent with the rest of the repo (single quotes around paths). DOCS = [ "docs/documentation/contributing.md", "docs/documentation/gpuParallelization.md", "docs/documentation/running.md", "docs/documentation/case.md", ".github/copilot-instructions.md", ".pr_agent.toml", ".coderabbit.yaml", ] # Match backtick-wrapped strings that look like repo-relative file paths PATH_RE = re.compile(r"`((?:src|toolchain|\.github|docs|examples|tests)/[^`]+)`") # Skip paths with placeholders, globs, or patterns (not real file paths) SKIP_RE = re.compile(r"[<>*()\[\]{}]|/\.\.\.|%|\$") def check_docs(repo_root: Path) -> list[str]: errors = [] for doc in DOCS: doc_path = repo_root / doc if not doc_path.exists(): continue text = doc_path.read_text() for match in PATH_RE.finditer(text): path_str = match.group(1) if SKIP_RE.search(path_str): continue # Strip trailing punctuation that may have leaked in path_str = path_str.rstrip(".,;:!?") if not (repo_root / path_str).exists(): errors.append(f" {doc} references '{path_str}' but it does not exist") return errors Robustness The new doc-reference check calls the script via python3 and relies on implicit stdout/stderr handling; consider ensuring consistent behavior across environments (virtualenvs, missing python3) and making the output actionable (e.g., forwarding the script’s exit code and clearly indicating which docs were scanned). # 5. Doc reference check log "[$CYAN 5/5$COLOR_RESET] Checking$MAGENTA doc references$COLOR_RESET..." if python3 toolchain/mfc/lint_docs.py 2>&1; then ok "Doc references are valid." else FAILED=1 fi Duplication The script hardcodes a DOCS allowlist that overlaps with existing doc/config sources; this can drift as docs are added/moved. Consider deriving the list from a docs directory glob plus explicit extra files, or centralizing the list so the same set is used in CI/precheck and elsewhere. DOCS = [ "docs/documentation/contributing.md", "docs/documentation/gpuParallelization.md", "docs/documentation/running.md", "docs/documentation/case.md", ".github/copilot-instructions.md", ".pr_agent.toml", ".coderabbit.yaml", ]

[cubic-dev-ai]

No issues found across 11 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[codeant-ai]

Nitpicks 🔍

🔒 No security issues identified

⚡ Recommended areas for review Path traversal / symlink handling The script constructs paths by simple concatenation (repo_root / path_str) and checks exists(). This can be fooled by '../' segments or symlinks. It's safer to resolve the candidate path and ensure it's within the repo root before reporting a missing file. False negatives / false positives SKIP_RE excludes strings containing characters like '%' and '$' which might legitimately appear in file names in rare cases, and the script skips docs that don't exist silently. Also stripping trailing punctuation (rstrip) may still leave markup artifacts. These choices can produce false negatives (missing real broken refs) and false positives (skipping valid ones). Path matching limitations The PATH_RE only matches backtick-wrapped, repo-relative paths that start with a short fixed set of prefixes (src, toolchain, .github, docs, examples, tests). This will miss many valid references (paths starting with ./, absolute-root-style '/', other directories, or paths not wrapped in backticks). Consider broadening path matching and normalizing extracted paths before existence checks. Precheck reporting UX The doc-reference check runs the Python script but doesn't capture or forward its stdout/stderr in a way that is easy to present to users when it fails. As-is, output could be mixed with other logs; failure only sets FAILED but doesn't preserve the tool output for clearer error messages. Also consider ensuring the python invocation runs from repo root regardless of current working directory.

[codeant-ai]

CodeAnt AI finished reviewing your PR.

[coderabbitai]

Actionable comments posted: 5

🤖 Fix all issues with AI agents

In @.coderabbit.yaml:
- Line 2: The language value in .coderabbit.yaml uses the wrong case ("language:
en-us"); update the language key to match the schema enum exactly by replacing
it with "en-US" (capitalized country code). Locate the top-level "language"
entry and change its value to "en-US" so it validates against the schema.

In @.github/CONTRIBUTING.md:
- Line 5: The markdown link text and target URL are inconsistent: the visible
text shows "mflowcode.github.io/documentation/md_contributing.html" while the
href points to "contributing.html"; update the markdown so the display text
matches the actual URL (or vice versa) in the line containing the link (the link
markdown with visible text
"mflowcode.github.io/documentation/md_contributing.html"), ensuring both the
anchor text and the href reference the same file name (either
md_contributing.html or contributing.html).

In `@docs/documentation/case.md`:
- Around line 239-241: Update the incorrect file pattern
"1[2,3]dHardcodedIC.fpp" in the docs to the correct pattern
"[1,2,3]dHardcodedIC.fpp" (or explicitly list "1dHardcodedIC.fpp,
2dHardcodedIC.fpp, 3dHardcodedIC.fpp") wherever the erroneous
"1[2,3]dHardcodedIC.fpp" string appears (see the documented example and the
referenced mention of patch_icpp(patch_id)%%hcid for context).

In `@docs/documentation/contributing.md`:
- Line 695: Replace the lowercase "markdown" with the proper noun "Markdown" in
the contributing guideline line that currently reads "Update **markdown docs**
under `docs/` if user-facing behavior changes" so it reads "Update **Markdown
docs** under `docs/` if user-facing behavior changes"; edit that text in
docs/documentation/contributing.md (the contributing guideline sentence) to
apply the capitalization fix.

In `@toolchain/mfc/lint_docs.py`:
- Around line 14-15: DOCS contains entries ".pr_agent.toml" and
".coderabbit.yaml" which won't match PATH_RE because they include bare TOML/YAML
paths not wrapped in backticks; remove these two strings from the DOCS list (or
alternatively update PATH_RE in the same module to also match bare string values
in TOML/YAML) so lint_docs.py's DOCS list only contains files whose path
patterns will be found by PATH_RE (refer to the DOCS variable and the PATH_RE
regex in this file).

🧹 Nitpick comments (3)

docs/documentation/contributing.md (1)

56-64: Add a language identifier to the fenced code block.

Markdownlint flags this block (MD040). Since it's a text diagram, use text or plaintext as the language identifier.

Suggested fix

-```
+```text
 q_cons_vf (conservative variables: density, momentum, energy, volume fractions)

toolchain/mfc/lint_docs.py (1)

27-30: Silently skipping missing doc files may hide breakage.

If a file in DOCS is renamed or deleted, this script won't report that the doc itself is gone — it just skips it. Consider logging a warning (or even treating it as an error) when a listed doc doesn't exist, so renames are caught early.

Proposed fix

         doc_path = repo_root / doc
         if not doc_path.exists():
+            errors.append(f"  Doc file '{doc}' listed in DOCS but does not exist")
             continue

toolchain/bootstrap/precheck.sh (1)

130-136: Minor inconsistency: no explicit error message on failure, unlike other steps.

The other steps call error "..." on failure to provide a uniform log style. Step 5 relies on lint_docs.py to print its own error output, which works but looks different from the rest. Consider adding an error call for consistency:

Proposed fix

 if python3 toolchain/mfc/lint_docs.py 2>&1; then
     ok "Doc references are valid."
 else
+    error "Doc reference check failed. See above for details."
     FAILED=1
 fi

[Copilot]

Pull request overview

This PR adds a comprehensive developer guide, streamlines the pull request template, and configures multiple AI code review tools to reference the new documentation. The changes consolidate scattered contribution guidelines into a single, authoritative source and add automated validation for documentation file references.

Changes:

• Adds comprehensive developer guide at docs/documentation/contributing.md covering architecture, coding standards, common pitfalls, and step-by-step how-to guides
• Introduces toolchain/mfc/lint_docs.py to automatically validate that file paths referenced in documentation actually exist
• Streamlines PR template and .github/CONTRIBUTING.md to redirect to the full developer guide
• Updates AI reviewer configurations (.pr_agent.toml, .github/copilot-instructions.md, .coderabbit.yaml, .codeant/configuration.json) to reference the new documentation
• Corrects hardcoded IC file path references in docs/documentation/case.md from src/pre_process/include/ to src/common/include/
• Adds doc reference check as step 5/5 in toolchain/bootstrap/precheck.sh

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
toolchain/mfc/lint_docs.py	New linting script that validates file path references in documentation remain accurate
toolchain/bootstrap/precheck.sh	Updates step numbering (1/4→1/5, etc.) and adds doc reference check as final step
docs/documentation/readme.md	Adds "Development" section with link to contributing guide
docs/documentation/contributing.md	New comprehensive 715-line developer guide covering architecture, standards, pitfalls, and how-to guides
docs/documentation/case.md	Corrects hardcoded IC patch file paths from src/pre_process/include/ to src/common/include/
.pr_agent.toml	Updates instructions to reference new documentation structure and prioritize correctness over style
.github/copilot-instructions.md	Streamlines and generalizes for multiple AI reviewers, references contributing.md for details
.github/CONTRIBUTING.md	Simplifies to redirect to full developer guide with quick reference
.github/pull_request_template.md	Streamlines from 58 to 32 lines, focuses on essentials, links to developer guide
.coderabbit.yaml	New configuration file for CodeRabbit AI reviewer
.codeant/configuration.json	New configuration file for CodeAnt AI reviewer