Skip to content

docs: secrets troubleshooting fixes + framework-version sweep (2.0 → 2.0+)#190

Merged
dimitri-yatsenko merged 2 commits into
mainfrom
docs/manage-secrets-troubleshooting
Jul 1, 2026
Merged

docs: secrets troubleshooting fixes + framework-version sweep (2.0 → 2.0+)#190
dimitri-yatsenko merged 2 commits into
mainfrom
docs/manage-secrets-troubleshooting

Conversation

@dimitri-yatsenko

@dimitri-yatsenko dimitri-yatsenko commented Jun 24, 2026

Copy link
Copy Markdown
Member

Summary

Two unrelated docs sweeps, bundled per request.

1. how-to/manage-secrets.md — troubleshooting fixes

  • Secrets Not Loading: removed the misleading
    print(dj.config._config_sources) # Not a real attribute, just conceptual
    line — copy-pasting it raises AttributeError. Replaced with a working
    snippet using find_config_file() / find_secrets_dir() from
    datajoint.settings, plus a note on what None means.
  • Accidentally Committed Secrets: reordered so credential rotation is the
    first concrete step. History rewrite is cleanup — it does not un-leak a
    secret that already reached a remote. Added a warning admonition and
    expanded step 1 with the specific credential classes (database user,
    object-store keys, third-party tokens) and an access-log audit.

2. Framework version: "DataJoint 2.0" → "DataJoint 2.0+"

The docs cover the entire 2.x line, not the 2.0 release specifically.
Updated product-level references in README.md and the how-to / reference /
tutorial pages that describe the framework as it currently exists.

Touched: README.md, src/how-to/installation.md,
src/how-to/deploy-production.md, src/how-to/migrate-to-v20.md,
src/reference/specs/fetch-api.md,
src/reference/specs/object-store-configuration.md,
src/tutorials/basics/04-queries.ipynb.

Intentionally left as-is (historical / release-specific):

  • whats-new-2.md, whats-new-21.md, whats-new-22.md (release-event pages)
  • versioning.md baseline references
  • Paper citations in citation.md / publications.md
  • "introduced in DataJoint 2.0" in type-system.md
  • pre-2.0 vs 2.0 implementation comparison in job-metadata.md
  • Literal CLI output in use-cli.md
  • autopopulate.md — "DataJoint 2.0 replaces the schema-level ~jobs table"
    describes the 2.0 release event (same rationale as job-metadata.md)
  • use-plugin-codecs.md — literal version pins (datajoint>=2.0.0) and
    plugin codec-versioning examples (2.0 → 3.0, codec_version = "2.0");
    illustrative/literal, not product-level prose

Test plan

  • mkdocs serve — both troubleshooting subsections + version-touched pages render cleanly
  • lychee passes locally (431 OK / 0 errors)

- Replace the non-existent dj.config._config_sources line with a working
  snippet that uses find_config_file / find_secrets_dir from
  datajoint.settings to show which paths were resolved.
- Reorder "Accidentally Committed Secrets" so credential rotation is the
  first concrete step — history rewrite is cleanup that doesn't un-leak the
  secret. Add a warning admonition spelling that out, and expand step 1
  with the specific credential classes to rotate (database, object store,
  third-party tokens) and the access-log audit.
The docs cover the entire 2.x line, not the 2.0 release specifically.
Switch product-level references from "DataJoint 2.0" to "DataJoint 2.0+"
in README and the how-to / reference / tutorial pages that describe the
framework as it currently exists.

Historical statements ("introduced in 2.0", "What's New in 2.0", paper
citation "DataJoint 2.0: A Computational Substrate...", pre-2.0 vs 2.0
implementation comparisons) intentionally keep their literal version
references.
@dimitri-yatsenko dimitri-yatsenko changed the title docs(secrets): real diagnostic snippet + rotate-first incident order docs: secrets troubleshooting fixes + framework-version sweep (2.0 → 2.0+) Jun 24, 2026
@dimitri-yatsenko

Copy link
Copy Markdown
Member Author

@MilagrosMarin when you have a moment, could you take a look? Two unrelated docs sweeps bundled here — the secrets-troubleshooting fixes (real diagnostic snippet + rotate-first incident order) and the framework-version sweep from "DataJoint 2.0" to "DataJoint 2.0+" in user-facing prose. The body lists what was intentionally left as historical (release-event pages, paper citations, etc.). No rush.

@MilagrosMarin MilagrosMarin left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Both changes land cleanly: the find_config_file() / find_secrets_dir() diagnostic snippet works against the actual datajoint.settings API, and the rotate-first framing for accidental commits is the correct incident-response order. The 2.0 → 2.0+ sweep is consistent.

Tiny nudge, optional: src/reference/specs/autopopulate.md and src/how-to/use-plugin-codecs.md still have "DataJoint 2.0" references that weren't updated. Both fit the same "release-specific / historical" rationale that keeps type-system.md unchanged, so leaving them as-is is defensible — worth adding to the "intentionally left as-is" list in the PR body for completeness.

Approving.

@dimitri-yatsenko

Copy link
Copy Markdown
Member Author

Thanks @MilagrosMarin — good catch. I checked both and agree they're not product-level prose, so I've documented them in the "intentionally left as-is" list rather than sweeping:

  • autopopulate.md — the "DataJoint 2.0 replaces the schema-level ~jobs table" line describes the 2.0 release event, same rationale as job-metadata.md.
  • use-plugin-codecs.md — every hit is a literal version pin (datajoint>=2.0.0), an illustrative semver example (2.0 → 3.0, 0.1.0 → 1.0.0 → 2.0.0), or the plugin's own codec_version = "2.0" in sample code. Sweeping those (e.g. datajoint>=2.0+.0) would be incorrect.

Updated the PR body accordingly.

@dimitri-yatsenko dimitri-yatsenko merged commit 7f4ca37 into main Jul 1, 2026
3 checks passed
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