Skip to content

docs: fix profile PyPI badge + flesh out root README (admin-only — org-admin write access required) #103

Description

@saqlainsyed007

Part of the cross-repo docs truth pass tracebloc/backend#962 (epic tracebloc/backend#958).

Why this is a separate issue

This is the one item of #962 that could not be landed by the assignee (@saqlainsyed007) — they have only pull permission on tracebloc/.github, so the branch cannot be pushed and no PR can be opened here.

⚠️ @LukasWodka — this one is yours alone. As the org admin you are the only person with write access to tracebloc/.github, so only you can apply and merge this change. Everyone else on the team is pull-only here.

What needs to change (two docs fixes, verified)

  1. profile/README.md — the PyPI badge points at the old distribution name tracebloc-package. The canonical package is now tracebloc (the SDK's pyproject.toml declares name = "tracebloc", and it is live on PyPI at v0.16.0). Repoint the shield + link to pypi.org/project/tracebloc.
  2. README.md — currently a 9-byte stub (# .github). Replace it with a real root README describing the repo (org profile, shared issue templates, reusable/caller CI workflows, CODEOWNERS, scripts/house-rules.sh).

Branch off develop, target develop (promotes to main the normal way).

Ready-to-apply patch

Save as fix.patch and git apply fix.patch from the repo root:

diff --git a/README.md b/README.md
index a46ae92..5325a99 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,36 @@
-# .github
\ No newline at end of file
+# .github
+
+Org-wide GitHub configuration for [tracebloc](https://github.com/tracebloc):
+the public org profile, shared issue templates, reusable CI/automation
+workflows, and code-ownership defaults. Files here apply across every repo in
+the org unless a repo overrides them locally.
+
+> Looking to deploy or use tracebloc? Start at the [org profile](profile/README.md)
+> or [docs.tracebloc.io](https://docs.tracebloc.io/). This repo is internal
+> tooling.
+
+## What's in here
+
+| Path | Purpose |
+|------|---------|
+| `profile/README.md` | The org's public profile, rendered at [github.com/tracebloc](https://github.com/tracebloc). |
+| `.github/ISSUE_TEMPLATE/` | Shared issue forms — `bug`, `feature`, `docs`, `tech-debt` — plus `config.yml` (the template chooser; blank issues disabled, routed to Slack). |
+| `.github/workflows/` | Org-wide **reusable** workflows and their thin per-repo **caller** workflows (see below). |
+| `.github/CODEOWNERS` | Default review ownership for this repo. |
+| `scripts/house-rules.sh` | POSIX-`sh`/`awk` house-rule checker run in CI — encodes the grep-level subset of agreed team rules so they fail (or report) at commit time instead of being re-flagged one PR at a time. |
+
+## Workflows
+
+Automation is split into **reusable** workflows (the logic, `workflow_call`)
+and **caller** workflows (a few lines per consuming repo that invoke the
+reusable one). The main families:
+
+- **Kanban board automation** — `add-to-kanban`, `kanban-closure-router` / `kanban-closure-caller`, `kanban-reconcile` (weekly backstop), `kanban-archive` (daily archive of terminal items).
+- **Deploy-environment advancement** — `advance-deploy-env` / `advance-deploy-env-caller`.
+- **PR status & review gates** — `set-pr-status` / `set-pr-status-caller`, `wip-limit-check` / `wip-limit-caller`, `fr-gate` (final-review gate), `fr-pass-comment` / `fr-pass-comment-caller`.
+- **Quality** — `code-quality` (reusable), `actionlint`, `public-pii-gate`, `customer-priority-bump`.
+
+## Branching
+
+Feature work targets `develop`; `develop` is promoted to `main` via a
+`chore(promote): develop → main` PR. (Matches the org-wide convention.)
diff --git a/profile/README.md b/profile/README.md
index d02234c..9641a2c 100644
--- a/profile/README.md
+++ b/profile/README.md
@@ -1,4 +1,4 @@
-[![Website](https://img.shields.io/badge/website-tracebloc.io-00C9A7.svg)](https://tracebloc.io) [![Docs](https://img.shields.io/badge/docs-docs.tracebloc.io-blue.svg)](https://docs.tracebloc.io) [![Discord](https://img.shields.io/badge/discord-join-7289DA.svg)](https://discord.gg/tracebloc) [![PyPI](https://img.shields.io/pypi/v/tracebloc-package.svg)](https://pypi.org/project/tracebloc-package/)
+[![Website](https://img.shields.io/badge/website-tracebloc.io-00C9A7.svg)](https://tracebloc.io) [![Docs](https://img.shields.io/badge/docs-docs.tracebloc.io-blue.svg)](https://docs.tracebloc.io) [![Discord](https://img.shields.io/badge/discord-join-7289DA.svg)](https://discord.gg/tracebloc) [![PyPI](https://img.shields.io/pypi/v/tracebloc.svg)](https://pypi.org/project/tracebloc/)
 
 # Build better AI together. Without moving data.

Verified against the current tree. Docs-only — no code or workflow changes.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions