Skip to content

feat: add community contribution folder - #37

Merged
LeoRoccoBreedt merged 14 commits into
mainfrom
lrb/community-folder
Jul 10, 2026
Merged

feat: add community contribution folder#37
LeoRoccoBreedt merged 14 commits into
mainfrom
lrb/community-folder

Conversation

@LeoRoccoBreedt

@LeoRoccoBreedt LeoRoccoBreedt commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Closes #17.

What this adds

A new top-level community/ folder where the open-source community can showcase what they build with Opik — kept deliberately separate from the maintainer-verified buckets (integrations/, guides/, use-cases/, scripts/) so nothing here reads as verified reference material.

Model (hybrid, showcase-first):

  • Listed (default): a self-contained folder per contribution — meta.yaml + README.md writeup + opik-proof.png — linking out to the contributor's own repo/blog/Colab.
  • Hosted (promoted): standout real-world work a maintainer promotes in-repo (code included, hosted: true), featured for the community forums.

Every entry must prove genuine Opik usage (Comet cloud or self-hosted OSS), and human PR review is the gate for both listing and promotion.

How it works

  • Contributors run nothing. They copy community/templates/entry-template/ to community/<author>_<project>/, fill in meta.yaml + README.md, drop in opik-proof.png, and open a PR.
  • Lightweight, non-executing check (community/_ci/check_entry.py, wired as the community-check.yml hard gate on community/** PRs). It never runs contributor code — it only validates statically:
    1. meta.yaml required fields + ≥1 link + valid opik_platform
    2. README's four sections filled in (no leftover TODO) — the anti-slop core
    3. opik-proof.png committed and referenced
    4. hosted entries contain real Opik usage (import opik / @opik.track / …)
    5. no committed .env / hardcoded keys (incl. sk-, sk-proj-, sk-svcacct-)
    6. folder name is <author>_<project>
  • The showcase index regenerates automatically on merge. community-index.yml runs build_index.py on push to main and commits the refreshed community/README.md back if it changed — no contributor or maintainer runs it by hand. (build_index parses YAML only; it never executes contributor code.)
  • community/ is excluded from the verified-bucket CI (compliance/pr-test/test-notebooks/scheduled are all path-scoped and never match community/**) — so contributors aren't bound by the strict run.sh/dry-run/litellm contract, and can use advanced models that maintainers review and run locally.
  • Maintainer/CI tooling lives in community/_ci/ (named so it clearly isn't community content and doesn't collide with the top-level scripts/ bucket). A relaxed community/CONTRIBUTING.md carries the light contract; the root README gains a Community section and root CONTRIBUTING points to it.
  • .gitignore un-ignores community/**/*.png (the repo's global *.png would otherwise silently drop proof screenshots).

Testing

  • 47 unit tests over the validators and index generator (community/_ci), ruff check/format clean.
  • End-to-end verified locally: an un-edited template copy is correctly rejected (placeholder sections), a filled-in sample passes and renders an index row, and teardown leaves the tree clean.

Review notes

Each commit was reviewed independently, plus a whole-branch review and a focused review of the hardening commit. Findings applied:

  • Gate hardeningdiscover_entries flags a contributor folder missing meta.yaml (previously it could slip the no-arg CI run); broadened secret scan to modern OpenAI key formats; escaped | in generated table cells.
  • Robustness — explicit encoding="utf-8" on all contributor-file reads (so non-ASCII READMEs/meta don't crash the gate on a non-UTF-8 runner).

Remaining known items are intentional lightweight-heuristic choices (substring placeholder matching; the secret scan as a best-effort scan with human review as the backstop).

Notes for reviewers

  • The community/ folder ships with no entries (empty-state index) — this PR is the contribution infrastructure, not content.
  • community-index.yml's push-back to main (commit-if-changed + the !community/README.md loop-guard) can't be fully exercised locally; the first real entry merge is where it fires end-to-end.

🤖 Generated with Claude Code

@LeoRoccoBreedt
LeoRoccoBreedt marked this pull request as ready for review July 3, 2026 13:49
@LeoRoccoBreedt
LeoRoccoBreedt requested a review from fschlz as a code owner July 3, 2026 13:49
@LeoRoccoBreedt LeoRoccoBreedt self-assigned this Jul 3, 2026
- Rename community/scripts -> community/_ci (maintainer/CI-only tooling; no
  longer collides with the top-level scripts/ bucket or invites contributors in)
- Drop the contributor "regenerate the index" step from community/CONTRIBUTING.md
- Remove the index-freshness gate from community-check.yml (PR gate is now just
  entry validation)
- Add community-index.yml: regenerate community/README.md from meta.yaml on
  merge to main and commit it back if changed (path-excludes README.md to avoid
  re-trigger); build_index parses YAML only, never runs contributor code
- Update RESERVED_DIRS and all path references

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@LeoRoccoBreedt
LeoRoccoBreedt merged commit 2fb8e4b into main Jul 10, 2026
1 check passed
@LeoRoccoBreedt
LeoRoccoBreedt deleted the lrb/community-folder branch July 10, 2026 15:17
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.

[FR]: Add community contribution folder

1 participant