Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/update-readme.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,20 @@ jobs:
run: dotnet tool install ktsu.KtsuBuild.Tool --tool-path ./.ktsubuild

# The tool reads the GitHub API through the gh CLI, which is preinstalled on the runner.
#
# The Status column keys on `ci.yml`, the caller every repository uses to reach the shared
# pipeline. `--fallback-workflow dotnet.yml` keeps a status showing for the repositories that
# have not been moved over yet, and logs a warning naming each one, so the flag comes off by
# itself once the warnings stop. It is accepted by the published tool as well, where it is
# simply never consulted, so this runs correctly whichever version is installed.
- name: Generate Readme
env:
GH_TOKEN: ${{ github.token }}
run: >
./.ktsubuild/ktsubuild profile readme
--org ktsu-dev
--exclude Sdk
--fallback-workflow dotnet.yml
--template ./profile/README.template
--output ./profile/README.md

Expand Down
11 changes: 9 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The profile README is generated by KtsuBuild, not by a script in this repository

```bash
dotnet tool install ktsu.KtsuBuild.Tool --tool-path ./.ktsubuild
./.ktsubuild/ktsubuild profile readme --org ktsu-dev --exclude Sdk
./.ktsubuild/ktsubuild profile readme --org ktsu-dev --exclude Sdk --fallback-workflow dotnet.yml
```

The command reads every public repository in the organization, appends a table to
Expand All @@ -34,6 +34,7 @@ The table carries Repo, Ships, Stable, SDK, Stars, Activity, and Status.
Useful while iterating:
- `--only <repo>` limits the run to one repository, which takes seconds rather than minutes
- `--verbose` reports the primary projects and lookups behind each row
- `--fallback-workflow dotnet.yml` is the migration crutch described below, not a permanent flag

The source lives in `KtsuBuild/Profile/` in the [KtsuBuild](https://github.com/ktsu-dev/KtsuBuild)
repository. Change the generator there, not here.
Expand All @@ -45,11 +46,17 @@ breaks one of these, fix the repository rather than teaching the generator about

| Convention | What breaks without it |
|------------|------------------------|
| The build workflow is named `dotnet.yml` | The Status column is blank |
| The repository calls the shared pipeline through `ci.yml` | The Status column is blank |
| Projects are named `<Repo>.csproj`, `<Repo>.App`, `<Repo>.ConsoleApp`, `<Repo>.Tool`, `<Repo>.Test` | Nothing directly, but the naming is what makes a repository readable |
| Demos, samples, examples, benchmarks, and tests are named for what they are, or live under `examples/`, `samples/`, `benchmarks/`, `tests/` | The Ships column claims deliverables the repository does not ship |
| `global.json` pins `ktsu.Sdk` | The SDK column is blank |

The Status column reads `ci.yml` rather than the pipeline it dispatches to, which is what lets
`ci-shared.yml` grow new languages and visibilities without the generator learning about any of
them. While repositories are still being moved onto the shared pipeline, `--fallback-workflow
dotnet.yml` keeps their status showing and logs a warning naming each one still to move. The flag
comes off once the warnings stop; it is a migration crutch, not part of the convention.

Known violations, each of which wants a fix in its own repository:
- **Schema** ships `SchemaEditor` and `SchemaTool`, which should be `Schema.Editor` and `Schema.Tool`
- **ThemeProvider** ships `ThemeProvider.Analysis`, an application at the repository root. Decide
Expand Down
16 changes: 16 additions & 0 deletions docs/shared-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,21 @@ identical in every repository — which removes the per-repository footgun descr
[`dependabot-auto-merge.md`]. Renaming the caller away from `CI`, or back to per-pipeline
names, silently stops Dependabot PRs merging.

## Interaction with the profile README

The Status column on the organization profile is the latest run of one workflow file on a
repository's default branch, and KtsuBuild reads that file **by name**. It reads `ci.yml` —
the caller, not the pipeline the caller dispatches to. That is deliberate for the same reason
the dispatcher exists: a repository that starts building through a new pipeline keeps its
badge without the generator being taught anything.

While repositories are still being moved over, [`update-readme.yml`] passes
`--fallback-workflow dotnet.yml`, so an unmigrated repository still shows a status and the run
logs a warning naming it. The flag comes off when the warnings stop.

A repository that has neither file reports no status, which is the intended signal for a
repository that has opted out of shared CI rather than a bug to work around.

## Adding a pipeline

1. Add the workflow to this repository with `on: workflow_call`.
Expand All @@ -180,3 +195,4 @@ No repository is edited unless it is changing what kind of repository it is.

[`ci-shared.yml`]: ../.github/workflows/ci-shared.yml
[`dependabot-auto-merge.md`]: ./dependabot-auto-merge.md
[`update-readme.yml`]: ../.github/workflows/update-readme.yml