Agent guidance for the DPG repos: one public guide in .github and a complete AGENTS.md in each repo

Aperta
  • Qualcosa non va?
#2,965 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Ambito
documentation

Direzione di ricerca

Start with oclapi2’s existing AGENTS.md as the model, then review its core/services/ examples and oclweb3’s src/common/plugins/loader.js extension point. Create the shared guide and fixed text in OpenConceptLab/.github, then prepare complete AGENTS.md and CLAUDE.md files for all nine listed repos. Done means each repo has its own commands, conventions, extension points, PR rules, and the required shared block; oclapi2 also includes the Elasticsearch and isolated compose recipes.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

component/docs decision/planning-needed signal/large-scope signal/low-risk signal/needs-human signal/well-specified stage/triaged type/docs

Coding agents read a repo's own AGENTS.md or CLAUDE.md. They don't read the org's .github repo, so they miss OCL's contribution rules, and those files say little about how OCL code is written. In most DPG repos the AGENTS.md holds only tool boilerplate. As a result, agent-written PRs add procedural modules to class-based code, invent layer names (providers/ where OCL uses services/), and add code that makes a DPG repo depend on something outside the DPG.

This ticket writes that guidance once, publicly, and points every DPG repo to it. It replaces ocl_issues#2709. Related: OpenConceptLab/ocl_online#568.

Acceptance criteria

  • A public guide in OpenConceptLab/.github, next to DIGITAL-PUBLIC-GOOD.md, covering:
    • how DPG code stays complete on its own (DPG rules 2, 4 and 5): the test; what open code may do on its own (record usage and show totals; protect the server based on load or abuse); extension points whose default allows everything; and optional connected-service clients that stay off until configured. Where a case is unclear, ask a maintainer;
    • coding conventions for the Django and React repos: logic goes in classes, following the existing service and model patterns; use the existing layer names (services/, models, serializers, views; in React, services/ and components/); add no new layer or top-level folders; look for an existing class or utility to extend before adding a file;
    • the contribution rules from CONTRIBUTING.md that agents miss: every PR links an issue (closes OpenConceptLab/ocl_issues#N) and carries a type/ label. Reuse the ocl-cli wording from ocl_issues#2709.
  • One short block of fixed text, kept in .github, that every DPG repo's AGENTS.md includes: this repository is part of the OCL DPG, the guide applies, with a link to it.
  • Each DPG repo has an AGENTS.md that is complete on its own: overview, layout, build, test and lint commands, conventions with that repo's real examples, extension points, PR rules, and the fixed block. The repos are oclapi2, oclweb3, oclweb2, oclmap, ocl-cli, ocldev, ocl_omrs, ocl-docs and ocl-design-system. oclapi2's current AGENTS.md is the model.
  • Each repo's CLAUDE.md is just @AGENTS.md. Tool-specific boilerplate that outside contributors can't use (the code-review-graph block) is removed from both files.
  • AGENTS.md ends with: "If an AGENTS.local.md file exists in this repo, read it too. It adds to this file and never relaxes the guide."
  • oclapi2's AGENTS.md adds the search_index --create step for a fresh Elasticsearch, and a recipe for running tests in an isolated compose stack per worktree.
  • One PR per repo. The .github guide merges first.

Code to cite as examples: oclapi2 core/services/; oclweb3 src/common/plugins/loader.js (an extension point with an empty default).

Lingua principale
Nessun dato sulla lingua
Stelle
4
Fork
2
Merge medio
2h 12m
PR unite (30g)
1

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OpenConceptLab/ocl_issues

Tutte le issue di OpenConceptLab/ocl_issues

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.