Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Explain the tier-naming axis: `Manual` means external-origin, not hand-entered

Cerrado
#267 9 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 3 días

@dimitri-yatsenko ya está trabajando en esto.

Desde el 20/8/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

The problem

The two most-used tier names describe opposite axes, and each one names the axis the other actually means:

  • Manual names the writer ("a person"), but the tier means the origin (data from outside the pipeline).
  • Imported names the origin ("from elsewhere"), but the tier means the writer (the table's own make()).

The docs are consistent and correct about what the tiers mean. It is the class names that cross over, and a reader who reasons from the names alone will land in the wrong place.

The docs already explain Manual in different words than its name

  • Table Declaration §1.2 — Manual is "Data inserted at runtime from outside the pipeline (users, instruments, ingestion scripts)". Two of the three examples are automated.
  • Computation Model — "Manual and Lookup tables are not auto-populated; they are the entry points where a pipeline's data originates."
  • Fan-Out Ingestion — "inserts into several entry-point tables (Manual or Imported)".

So the concept is already named "entry point" throughout the prose. Only the class is called Manual.

The failure mode this produces

A designer building an automated feed reasons, reasonably: "this table isn't filled manually — a sync script fills it — so it isn't Manual. It comes from outside, so it's Imported." They declare dj.Imported.

But Imported is defined as "populated by make()", and this table has no make() — it's filled by insert from elsewhere. So the insert is refused, and the fix that presents itself is allow_direct_insert=True rather than a corrected tier.

The result is a recognizable and diagnosable shape:

  • an Imported table with no make(), which reads to every later reader as a table whose make() was forgotten;
  • populate() on it silently doing nothing rather than erroring;
  • a permanent allow_direct_insert=True suppressing a guard that was reporting a real problem;
  • the pipeline's actual boundary with the outside world drawn one table away from where it is.

Every step of that reasoning is sound except the premise that "manual" means "by hand."

Suggested docs changes (the near-term ask)

  1. State the axis explicitly, once, where tiers are introduced: the tier says how rows arrive, not who causes them to arrive. Rows inserted from outside the table → Manual; rows produced by the table's own make() → Imported (reads an external source) or Computed (derives from other tables).
  2. Say plainly that "manual" means external-origin, not hand-entered — an automated ingestion script inserts into a Manual table. The reference table hints at this with "ingestion scripts"; it deserves a sentence, not a parenthetical.
  3. Add the failure mode as a short "common mistake" callout — an Imported table with no make(), and allow_direct_insert as its tell. It is cheap to check and hard to spot by eye.
  4. Consider a small 2×2 (origin: external / derived × writer: inserted / make()) — it makes Lookup and Part sit naturally alongside the other three and shows why only four of the cells are populated.

Forward-looking: a better name

dj.Entry would name the thing itself — a table where data enters the pipeline, by whatever hand — and it matches the vocabulary the explanation pages already use. It carries no implication about who or what does the writing, which is the whole source of the confusion.

That is a datajoint-python change, not a docs change, so it needs a decision there. Filing it here because the explanation is the fix available now and the naming question follows from it. If it were taken up, the obvious shape is dj.Entry as the primary name with dj.Manual kept permanently as a backward-compatible alias — no deprecation, no migration, existing pipelines and tutorials keep working, and new material can teach the clearer name. Renaming Imported is a harder call and probably not worth it; once the axis is stated, Imported reads correctly as "imported by this table."

Happy to open a PR for items 1–3 if the framing looks right.

Lenguaje dominante
Jupyter Notebook
Estrellas
7
Forks
12
Merge medio
2 d 19 h
PR fusionados (30 d)
20

Preparar el entorno

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de datajoint/datajoint-docs

Todos los issues de datajoint/datajoint-docs

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.