KennisBank

Pre-publicatie checklist GitHub repos

Uit wiki.jimvandenbreemen.nl, de persoonlijke kennisbank van Jim van den Breemen

7 minuten leestijd

Pre-publicatie checklist GitHub repos

Definitie

Een zeven-blokken verificatie die elke repo doorloopt voor hij publiek gaat (nieuwe publieke repo, van privé naar publiek, push naar een publieke remote, release tag). Het doel is dat een externe gebruiker de repo kan clonen, installeren en gebruiken zonder kennis van de auteur, lokale machine of interne workflow. Het resultaat is een expliciet GO / NO-GO verdict met harde blockers en zachte adviezen apart.

Context

Eerdere repo-publicaties werden ad-hoc gecheckt: grep op API keys, kijken naar de README, klaar. Twee sessies maakten duidelijk dat die aanpak structureel lekken nalaat die niet met keys te maken hebben. Bij eindredacteur stond de auteursnaam in plugin.json en README terwijl de lokale versie (v0.4.0) bovendien niet overeenkwam met origin/main (v0.2.0). Bij project-handoff-skill bleek een volledige map test-output van een persoonlijke Hugo-site gecommit, plus absolute /Users/<name>/ paden in vijf inventory.json bestanden. Geen daarvan zou door een keys-grep worden gevangen.

De checklist is daarom gecodificeerd als de skill publish-repo-check in ~/.claude/skills/publish-repo-check/SKILL.md en triggert op zinnen als “klaar voor publicatie”, “publish repo” of “make public”. Hij geldt voor elk type repo: library, CLI, Claude Code plugin, Cowork plugin, documentatie-site.

Kernpunten

Blok 1: persoonlijke en identificerende informatie

Grep de hele repo op voornaam, achternaam, e-mailadressen (behalve generieke noreply@), GitHub handles (behalve in onvermijdelijke URLs), telefoonnummers, adressen, werkgevers, opleidingen, lokale paden (/Users/<name>/, /home/<name>/, C:\Users\<name>\), en verwijzingen naar andere privé-projecten of mappen van de auteur (projects/, me/, vault/). Blocker bij vondst in README, LICENSE metadata, plugin.json/package.json author velden, code comments, voorbeelden en changelog. Advies bij voorbeelden die toevallig een stad of bedrijf noemen die niet expliciet de auteur identificeren, tenzij ze als [fictief] gemarkeerd zijn.

Git commit email: persoonlijk emailadres in git commit metadata is zichtbaar op publieke repos. Preventie: git config --global user.email "<user>@users.noreply.github.com" + GitHub Settings > Emails > “Keep my email addresses private”. Bestaande commits behouden het oude adres; dat is niet te wijzigen zonder history rewrite. Geen blocker, wel standaard advies bij eerste publicatie.

Blok 2: licentie

Een LICENSE of LICENSE.md bestand in de root, of een licentie-veld in het manifest (package.json, plugin.json, pyproject.toml, Cargo.toml), bij voorkeur beide. Zonder licentie is de code standaard “all rights reserved” en mag niemand het wettelijk hergebruiken; dat maakt het geen open source maar “kijkbare code”. Standaard is MIT; vraag expliciet als er copyleft code (GPL) in zit, of als bundelde media onder een aparte licentie valt (CC-BY-SA voor content). De copyright-regel hoeft geen persoonsnaam te bevatten. Copyright (c) <jaar> <projectnaam> contributors is een geldig MIT-patroon dat plugin-managers accepteren en waarmee je GitHub-username alleen nog via de repo-URL zichtbaar is (een onvermijdelijke tweede-orde referentie).

Blok 3: installatie-instructies matchen werkelijkheid

Vanaf een verse clone moet een externe gebruiker de repo kunnen installeren op basis van alleen de README. Elk commando, pad en bestand dat de installatiesectie noemt moet bestaan. Voor plugins: per platform een eigen installatie-sectie (Claude Code, Cowork, VS Code extension). Voor CLI tools: installatie via package manager getest of realistisch. Voor libraries: het importvoorbeeld moet met de huidige API overeenkomen.

Blok 4: README matcht werkelijkheid

Features genoemd in README moeten bestaan in de code. Commands, endpoints, skills en functies die opgesomd worden moeten matchen met bestanden. Versienummer in README, manifest en CHANGELOG moet gelijk zijn. Interne links mogen niet dood zijn. De typische blocker hier: de README belooft een /command dat na een refactor alleen nog als skill bestaat, waardoor nieuwe gebruikers het niet kunnen aanroepen zoals gedocumenteerd.

Blok 5: secrets en git history

Grep op API keys (sk-, ghp_, ghs_, AKIA, xoxb-, xoxp-), .env bestanden, credentials.json, *.pem, *.key, database URLs met credentials, webhook URLs met tokens, en hardcoded wachtwoorden. Cruciaal: de scan moet git history meenemen, niet alleen de working tree. Een bestand dat later is verwijderd is nog steeds publiek zodra de repo publiek wordt. Credentials in git history vereisen rotatie van de credential zelf als fix; een force-push is vrijwel altijd een schijnoplossing omdat de commit al elders gecached kan zijn.

git log --all --full-history -p | grep -iE "api[_-]?key|secret|token|password|BEGIN (RSA|OPENSSH) PRIVATE"

Zie ook wiki-secrets-safeguard-project-handoffs voor de bredere filters die gelden bij project-handoffs; de publicatie-check is een subset die op elke repo van toepassing is.

Blok 6: bundelde content en derden-rechten

Bevat de repo samenvattingen, fragmenten of afbeeldingen uit boeken, papers, nieuwsartikelen? Externe assets (fonts, icons, plaatjes) met eigen licentie? Vendored dependencies zonder licentievermelding? Blocker bij substantiële fragmenten uit copyrighted werk boven wat fair use toestaat. Advies om een NOTICE of THIRD_PARTY_LICENSES bestand toe te voegen waar bronnen, auteurs en licenties van gebundeld materiaal vermeld staan. Voor eindredacteur gaat het om samenvattingen van zeven journalistieke vakboeken, niet hele hoofdstukken; dat past binnen fair use maar verdient expliciete bronvermelding in de README (wat er ook staat).

Blok 7: repo hygiëne

.gitignore aanwezig en passend bij de stack. Geen node_modules/, __pycache__/, .DS_Store, *.log of build artifacts in git. Publicatie-branch klaar op main of master, niet op een persoonlijke feature branch. Matcht je lokale HEAD met wat je denkt dat publiek komt? Zijn er uncommitted changes of unpushed commits die eigenlijk mee moeten? Als je een release bedoelt: staat de tag er? Optioneel maar aanbevolen voor serieuze projecten: CONTRIBUTING.md, CODE_OF_CONDUCT.md, issue en PR templates.

De eindredacteur publicatie-check ving hier een subtiele maar belangrijke blocker: origin/main stond op v0.2.0 terwijl lokaal v0.4.0 draaide met 13 extra skills en een volledige verificatielaag. Niets daarvan was gecommit. Zonder deze check was die mismatch pas na publicatie opgevallen.

npm CLI-tools: bin-path en package.json exports

npm bin-path. De bin-entry in package.json accepteert géén leading ./: "bin": { "mytool": "./dist/cli.js" } wordt door npm stil als invalide beschouwd en bij publish verwijderd. Het binary is dan niet installeerbaar. De correcte vorm is "bin": { "mytool": "dist/cli.js" }. npm pkg fix corrigeert dit automatisch. Signaal: npm publish --dry-run toont een npm warn publish "bin[name]" script name was invalid and removed. Altijd de warn-output lezen, niet alleen de exit-code.

TypeScript ESM exports volgorde. In het exports-veld moet types altijd vóór import (en voor require) staan. TypeScript resolveert export-condities in declaratievolgorde en stopt bij de eerste match. Als import voor types staat, vindt een TypeScript-consumer de types niet.

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js"
  }
}

Beide worden niet gevangen door een keys-grep en zijn pas zichtbaar bij npm publish --dry-run of een downstream TypeScript-installatie.

Rapportformat

## Publication check: <repo-naam>

**Verdict:** GO / NO-GO

### Blockers (moeten opgelost voor publicatie)
- [blok N] <bestand:regel> — beschrijving

### Adviezen (niet blokkerend)
- [blok N] <bestand:regel> — beschrijving

### Nog te bevestigen met gebruiker
- Licentiekeuze
- Eventuele structurele beslissingen

Regel: push pas na expliciete bevestiging

Ook bij verdict GO volgt push pas na expliciete bevestiging van de gebruiker. Licentiekeuze, structurele wijzigingen en release timing zijn beslissingen die de mens maakt, niet de skill. De skill rapporteert en wacht.

Verbanden

Bronnen

Geen externe bronnen. Patronen komen uit drie praktijk-sessies: het publicatie-klaar maken van Jvdbreemen/eindredacteur (v0.4.1) en Jvdbreemen/project-handoff-skill op 2026-04-16, een eerdere ad-hoc repo-check op 2026-04-10, en de publicatie van Jvdbreemen/scrollytelling-plugin op 2026-04-22. De scrollytelling-casus bevestigde het patroon en voegde een categorie toe: theme-specifieke paden (themes/jvdb/) als persoonlijke referentie die niet door een keys-grep wordt gevangen maar wel de plugin onbruikbaar maakt voor externe gebruikers.

Sessie-herkomst

Verbanden

  1. Zie ook: wiki-slash-commands-vs-skills (plugin wrappers met ${CLAUDE_PLUGIN_ROOT} en de manier waarop plugins hun publicatie-interface definiëren)
  2. Zie ook: wiki-secrets-safeguard-project-handoffs (secrets filters bij handoff-generatie, bredere context voor blok 5)
  3. Zie ook: wiki-plugin-versioning-workflow (versiebeheer, changelog-discipline)
  4. Zie ook: wiki-gh-cli-workflow-scope (gh CLI voor repo-inventarisatie en visibility-checks)
  5. Gerelateerd project: 03-projecten/eindredacteur
  6. Gerelateerd project: 03-projecten/project-handoff-skill
  7. Zie ook: wiki-github-repo-aanmaken-lokaal — references

Backlinks

Grafiekweergave