Skip to content

Add repository-backed GitHub wiki sync#1318

Open
dgruss wants to merge 1 commit into
UltraStar-Deluxe:masterfrom
dgruss:wiki
Open

Add repository-backed GitHub wiki sync#1318
dgruss wants to merge 1 commit into
UltraStar-Deluxe:masterfrom
dgruss:wiki

Conversation

@dgruss
Copy link
Copy Markdown
Contributor

@dgruss dgruss commented May 24, 2026

This PR:

  • Adds the current GitHub wiki pages under wiki/ so wiki changes can be reviewed through normal PRs.
  • Adds a Sync Wiki GitHub Actions workflow that mirrors wiki/** to UltraStar-Deluxe/USDX.wiki.
  • Documents the wiki sync setup in PIPELINE.md.
  • Updates the config.ini wiki page with the Linux config path lookup behavior.

Maintainer Instructions (to set this up)

Before merging or before the first sync run, add a repository secret named WIKI_TOKEN.

WIKI_TOKEN must be a token that can push to:

https://github.com/UltraStar-Deluxe/USDX.wiki.git

After this PR is merged, the checked-in wiki/ directory becomes the source of truth. The workflow uses rsync --delete, so direct edits made only in the GitHub wiki are overwritten by the next sync unless they are first copied back into wiki/.

The workflow runs on pushes to master that change wiki/** or .github/workflows/sync-wiki.yml. It can also be started manually from the Actions tab via workflow_dispatch.

Longer-term Direction

This keeps the existing GitHub wiki working, while allowing wiki changes through normal PRs.

GitHub Pages may still be the better long-term solution. It would avoid the separate .wiki.git repository and the extra WIKI_TOKEN. I did not do that here because it is a larger migration: existing wiki links, URL structure, and the fate of the old wiki would need a maintainer decision.

I could not properly test this PR and I'm not sure how to proceed here. Merging and seeing if it works? Not sure if that's the right approach...

This PR would allow addressing issues #1159 (with a small addition in the wiki), #660, and #80 (if we decide wiki is the one place for documentation and not some tex / pdf.

@barbeque-squared
Copy link
Copy Markdown
Member

GitHub Pages may still be the better long-term solution.

We do have the usdx.eu page, would that be a possibility? It's just a static website, and since I made 660 I have found the github wiki to be a bit... lacking. Especially the way pages are structured, almost impossible to rename, and there's always the tree view with 80% random garbage that's not relevant to what you're looking for at any point in time.

Obviously this could still be a good short-term improvement, I'm just wondering if it's worth setting up if there is also that alternative. I don't know what would be logical from a user standpoint either (I think 90% of the wiki is for users? there's very little for developers on there iirc)

PS: regardless of what we'd do, I'd import the current with some git-filter-repo magic. It will keep the complete history of those files.

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