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
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
16 changes: 8 additions & 8 deletions .claude/skills/sync-docs-after-overhaul/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: sync-docs-after-overhaul
description: Bring KDoc comments and the markdown guides under Archie/docs/ back in sync after a significant refactor or architecture overhaul in this repo (renamed classes, restructured hierarchies, new/removed APIs, changed method signatures). Use this whenever the user says they "overhauled", "refactored", "restructured", or "rewrote" a system and asks to update docs, or whenever you notice staged/unstaged changes that rename or gut core classes in an area that has a doc guide (config, events, gui, networking, registries, resource-packs, serialization, transfer). Don't reach for this for a small fix or single-file change — it's for the case where the shape of a system changed enough that existing docs now describe something that no longer exists.
description: Bring KDoc comments and the markdown guides under docs/ back in sync after a significant refactor or architecture overhaul in this repo (renamed classes, restructured hierarchies, new/removed APIs, changed method signatures). Use this whenever the user says they "overhauled", "refactored", "restructured", or "rewrote" a system and asks to update docs, or whenever you notice staged/unstaged changes that rename or gut core classes in an area that has a doc guide (config, events, gui, networking, registries, resource-packs, serialization, transfer). Don't reach for this for a small fix or single-file change — it's for the case where the shape of a system changed enough that existing docs now describe something that no longer exists.
---

# Sync docs after an overhaul
Expand Down Expand Up @@ -35,19 +35,19 @@ critically, the same as an external markdown guide.

Check all of these, not just the obvious one:

- **The dedicated markdown guide**, if this feature area has one — `Archie/docs/config.md`,
- **The dedicated markdown guide**, if this feature area has one — `docs/config.md`,
`events.md`, `gui.md`, `networking.md`, `registries.md`, `resource-packs.md`,
`serialization.md`, `transfer.md`. Find it with `ls Archie/docs/`; don't guess a name.
- **`Archie/docs/index.md`**, which has a one-line feature-overview table entry per area — usually
`serialization.md`, `transfer.md`. Find it with `ls docs/`; don't guess a name.
- **`docs/index.md`**, which has a one-line feature-overview table entry per area — usually
just needs a phrase added/adjusted, rarely a rewrite.
- **Class- and member-level KDoc** in the overhauled files themselves, *and* in any other file that
references the overhauled types (grep for the old and new type names across
`Archie/common/src/main/kotlin` and the loader modules to catch call sites whose doc comments
now describe stale behavior).
`core/common/src/main/kotlin` and the loader/datagen/gametest/test modules to catch call sites
whose doc comments now describe stale behavior).
- **Grep the whole repo for old names** (`grep -rn OldClassName`) to catch stragglers a targeted
read would miss — renames especially leave orphaned references in comments that don't affect
compilation and so never surface as errors.
- **README.md / AGENTS.md** — usually just point at `Archie/docs/`, so low priority, but check if
- **README.md / AGENTS.md** — usually just point at `docs/`, so low priority, but check if
either names a specific API that changed.
- **Archie-Test** — the dev-playground module sometimes demonstrates a feature area directly; check
whether it does before ruling it out.
Expand Down Expand Up @@ -82,7 +82,7 @@ rest of the file, mismatched brackets in a code fence, etc. After editing source
for markdown-only edits), run the relevant compile task, e.g.:

```
./gradlew :Archie:common:compileKotlin -q
./gradlew :archie-core-common:compileKotlin -q
```

Treat a clean compile as confirmation the edits are syntactically sound — it says nothing about
Expand Down
2 changes: 1 addition & 1 deletion .github/scripts/generate_release_notes.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
- Post-tag (.github/workflows/release-notes.yaml): --new-tag is a real, already-pushed tag; used
as both the git ref to end the walk at and the version display string. Writes both the
changelog section and a news post.
- Pre-publish (Archie/build.gradle.kts's `generateChangelog` task): the tag doesn't exist yet at
- Pre-publish (build.gradle.kts's `generateChangelog` task): the tag doesn't exist yet at
this point, so pass --new-tag as the *intended* version (e.g. `v1.2.0`, not yet a real ref)
together with --range-end HEAD (or another real ref) to walk up to. Only pass --changelog-path,
not --posts-dir, in this mode - modpublisher's `changelog = file(...)` needs CHANGELOG.md
Expand Down
25 changes: 13 additions & 12 deletions .github/workflows/check.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ jobs:
fail-fast: false
matrix:
loader: [fabric, neoforge]
side: [server, client]
runs-on: ubuntu-latest
timeout-minutes: 40
env:
Expand Down Expand Up @@ -63,30 +64,30 @@ jobs:
env:
GITHUB_ACTOR: ${{ github.actor }}
GITHUB_TOKEN: ${{ github.token }}
run: xvfb-run --auto-servernum --server-args="-screen 0 1280x1024x24" ./gradlew check --console=plain -Darchie.junit.gametest.matrix=${{ matrix.loader }}:server,${{ matrix.loader }}:client
run: xvfb-run --auto-servernum --server-args="-screen 0 1280x1024x24" ./gradlew check --console=plain -Darchie.junit.gametest.matrix=${{ matrix.loader }}:${{ matrix.side }}

- name: Publish test report
if: success() || failure()
uses: mikepenz/action-junit-report@v6
with:
check_name: JUnit Test Report (${{ matrix.loader }})
# Matrix expansion names this job "check (fabric)"/"check (neoforge)", not just "check" -
# without this, the action's default job_name (the raw job id "check") doesn't match any
# actual check-run on this commit, and its annotations silently land on an unrelated job
# (observed: the docs workflow's job) instead of failing loudly.
job_name: check (${{ matrix.loader }})
check_name: JUnit Test Report (${{ matrix.loader }}, ${{ matrix.side }})
job_name: check (${{ matrix.loader }}, ${{ matrix.side }})
report_paths: '**/build/test-results/test/TEST-*.xml'

- name: Upload test reports
if: always()
uses: actions/upload-artifact@v7
with:
name: test-reports-${{ matrix.loader }}
name: test-reports-${{ matrix.loader }}-${{ matrix.side }}
path: |
Archie/**/build/reports/tests/**
Archie/**/build/tmp/junit-gametest-runner/**
Archie-Test/**/build/reports/tests/**
Archie-Test/**/build/tmp/junit-gametest-runner/**
core/**/build/reports/tests/**
core/**/build/tmp/junit-gametest-runner/**
datagen/**/build/reports/tests/**
datagen/**/build/tmp/junit-gametest-runner/**
gametest/**/build/reports/tests/**
gametest/**/build/tmp/junit-gametest-runner/**
test/**/build/reports/tests/**
test/**/build/tmp/junit-gametest-runner/**
build/reports/problems/**
if-no-files-found: ignore
retention-days: 7
3 changes: 1 addition & 2 deletions .github/workflows/docs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,13 @@ jobs:
- uses: actions/cache@v6
with:
key: mkdocs-material-${{ env.cache_id }}
path: Archie/.cache
path: .cache
restore-keys: |
mkdocs-material-
- run: sudo apt-get update && sudo apt-get install -y pngquant
- run: pip install mkdocs-material mike mkdocs-rss-plugin cairosvg
- run: git fetch origin gh-pages --depth=1
- name: Build Documentation
run: ./gradlew publishDocs
working-directory: Archie
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
10 changes: 5 additions & 5 deletions .github/workflows/release-notes.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: release-notes

# Generates Archie/CHANGELOG.md and a dated Archie/docs/news/posts/ blog entry for a tagged
# Generates CHANGELOG.md and a dated docs/news/posts/ blog entry for a tagged
# release, then opens a PR with both. See .github/scripts/generate_release_notes.py for how
# entries are sourced (merged PR titles, parsed for a Conventional Commits prefix) and
# .github/workflows/pr-title-lint.yml for how those titles are kept in that shape.
Expand Down Expand Up @@ -54,14 +54,14 @@ jobs:
python .github/scripts/generate_release_notes.py \
--repo "${{ github.repository }}" \
--new-tag "${{ github.ref_name }}" \
--changelog-path Archie/CHANGELOG.md \
--posts-dir Archie/docs/news/posts
--changelog-path CHANGELOG.md \
--posts-dir docs/news/posts

- name: Open pull request
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
if git diff --quiet -- Archie/CHANGELOG.md Archie/docs/news/posts; then
if git diff --quiet -- CHANGELOG.md docs/news/posts; then
echo "Nothing new to record since the previous tag - skipping PR."
exit 0
fi
Expand All @@ -71,7 +71,7 @@ jobs:

BRANCH_NAME="release-notes/${{ github.ref_name }}"
git checkout -b "$BRANCH_NAME"
git add Archie/CHANGELOG.md Archie/docs/news/posts
git add CHANGELOG.md docs/news/posts
git commit -m "docs: release notes for ${{ github.ref_name }}"
git push origin "$BRANCH_NAME"

Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ local.properties
docs/api
site
.architectury-transformer
.kotlin
*/.kotlin
__pycache__/
*.pyc
Expand Down
Loading
Loading