Skip to content

Consolidate contributing guide + fix test-running docs#399

Merged
gbeane merged 2 commits into
mainfrom
chore/consolidate-contributing-docs
Jun 19, 2026
Merged

Consolidate contributing guide + fix test-running docs#399
gbeane merged 2 commits into
mainfrom
chore/consolidate-contributing-docs

Conversation

@gbeane

@gbeane gbeane commented Jun 17, 2026

Copy link
Copy Markdown
Collaborator

Two related developer-documentation cleanups.

1. Consolidate the contributing guide

The contributing guide existed as two divergent copies — root CONTRIBUTING.md and docs/development/contributing.md (121 lines each, with hand-adjusted and partly broken internal links). This consolidates to a single source of truth:

  • Canonical file: root CONTRIBUTING.md (the conventional, GitHub-surfaced location).
  • Docs site: docs/development/contributing.md is now a one-line pymdownx.snippets include (--8<-- "CONTRIBUTING.md") so the page stays in the nav with no duplicated content. (Symlinking was tried first, but zensical 0.0.34 silently skips symlinked files.)
  • Fixed the broken links in CONTRIBUTING.md; cross-references now use absolute published-docs URLs so they resolve both on GitHub and in the rendered site. Fixed the two broken ../CONTRIBUTING.md links in development.md; pointed CLAUDE.md at the canonical root file. README.md already linked to root.
  • Verified with zensical build (no warnings; the page renders the canonical content).

2. Fix the test-running docs (and make pytest work)

Bare pytest from the repo root failed to collect — it recursed into packages/*/tests, hitting cross-package test-module name collisions (ImportPathMismatchError) — yet the docs told contributors to run pytest.

  • Added [tool.pytest.ini_options] testpaths = ["tests"] to the root pyproject.toml so bare pytest / uv run pytest runs the application suite cleanly. Explicit paths (e.g. pytest packages/jabs-core/tests) still work and override the default.
  • Updated the test-running instructions in CONTRIBUTING.md and docs/development/development.md to distinguish the main suite from the per-package suites (matching the per-package list already in CLAUDE.md).
  • Verified: bare pytest now collects and passes the full tests/ suite (710 tests); explicit package paths still collect.

Out of scope: docs/development/development.md also has a separate pre-existing broken link to user-guide.md (unrelated) — left for a follow-up.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR consolidates the contributing guide to a single canonical source (/CONTRIBUTING.md) and updates documentation cross-links so the contributing content stays consistent across GitHub and the rendered docs site.

Changes:

  • Replaced docs/development/contributing.md with a pymdownx.snippets transclusion of the root CONTRIBUTING.md.
  • Updated references in the development guide and CLAUDE.md to point at the canonical contributing guide location.
  • Fixed previously broken contributing/development/user-guide links in CONTRIBUTING.md by switching to the published docs URLs.

Reviewed changes

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

File Description
docs/development/development.md Updates “Looking to contribute?” references to point at the published Contributing Guide page.
docs/development/contributing.md Replaces duplicated content with a snippets include of the root CONTRIBUTING.md.
CONTRIBUTING.md Fixes broken internal links by pointing to the published docs URLs.
CLAUDE.md Updates the contributing-guide reference to the canonical root CONTRIBUTING.md.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@gbeane gbeane changed the title Consolidate contributing guide to a single source Consolidate contributing guide + fix test-running docs Jun 19, 2026
@gbeane gbeane merged commit 1d2e167 into main Jun 19, 2026
5 checks passed
@gbeane gbeane deleted the chore/consolidate-contributing-docs branch June 19, 2026 18:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants