Compare commits

...
32 changed files with 414 additions and 58 deletions

No files matched your search

+1 -1
View File
@@ -6,7 +6,7 @@ on:
pull_request:
paths: [tools/sync_history.py, tools/test_sync_history.py, changelog/history.json, .github/workflows/changelog.yml]
release:
types: [published, released]
types: [published, prereleased, released]
workflow_run:
workflows: [release]
types: [completed]
+4
View File
@@ -31,6 +31,10 @@ Optional: one short paragraph in plain English for the reader (at most 300 chara
## Shared build and release workflow
Every published Manager version, including a clearly marked Pre-release, belongs in this repository's
CHANGELOG.md and changelog/history.json. Its GitHub release notes use the same reviewed record.
Promotion updates that entry without duplicating it; Manager and server histories remain separate.
Before preparing or publishing a Manager/server release, read the maintained
[release runbook](https://github.com/Corfirean/coa-server-build/blob/main/docs/server-release.md)
and [build agent instructions](https://github.com/Corfirean/coa-server-build/blob/main/AGENTS.md).
+21
View File
@@ -4,8 +4,29 @@ Manager releases only. Updating the Manager does not update the server.
[Server changelog](https://github.com/Corfirean/coa-server-build/blob/main/CHANGELOG.md)
Published releases and previews. Pre-release entries do not change the stable update channel.
Dates follow GitHub publication (UTC); legacy records retain their archived dates. Newest releases first.
## 0.7.0 — 2026-10-21
Portable transfers into Warcraft Reborn are not supported yet.
**Portable Characters are experimental and may contain bugs.**
- Keep portable characters and their saved versions in the Manager, and use them on compatible realms.
- Make an existing character portable from a connected realm.
- Browse public realms and see their connection details.
- Link an existing realm account or create one on hosts that allow it.
- Switch between CoA, Wildcard and Warcraft Reborn realm profiles on supported server builds.
- Adjust creature health for different locations and enemy types in Content Scaling.
- Switch Custom Races patches faster, with visible feedback while changes are applied.
- Handle Windows requests for administrator permission when launching the game.
[Release](https://github.com/Corfirean/coa-server-manager/releases/tag/v0.7.0) · [Source changes](https://github.com/Corfirean/coa-server-manager/compare/v0.6.22...v0.7.0)
[Player guides and screenshots](https://github.com/Corfirean/coa-server-manager/tree/d22ff09ac6fd7628aac14d90ec23f547cd9b4bf1/docs)
## 0.6.22 — 2026-10-19
- Updated Custom Races client patches to 1.8.
+29 -16
View File
@@ -1,12 +1,16 @@
# CoA Server Manager
**Portable characters are experimental.** This feature is in active development and may contain bugs.
A Windows app that installs and runs your own **Conquest of Azeroth** server (AzerothCore) with a few clicks:
no console, no config files, no database tools. Tauri 2 + Rust + React.
![Overview](docs/screenshots/play.png)
![Your server at a glance](docs/screenshots/overview.png)
## What it does
* **Portable characters (Experimental).** Keep saved characters in the Manager, review their saved versions and make an existing character portable from a realm you can access. See the [short guide](docs/PORTABLE-CHARACTERS.md).
* **Find a realm.** Browse public realms and compare their game modes, level caps, rates, modules and population.
* **One-click install.** Downloads a signed, verified server package (resumable, checked file by file), sets up the
database and creates your first account. Or import a server you already have.
* **Start / Stop / PLAY.** One button for the whole server (database, auth, world) with live status, uptime and
@@ -18,14 +22,14 @@ no console, no config files, no database tools. Tauri 2 + Rust + React.
into **UPDATE**. Updates are authenticated (Ed25519), back up first, keep files you changed and can be rolled back.
* **Backups.** Characters, accounts and settings on demand, automatically before every update; verify and restore
from the app.
* **CoA / Wildcard realms.** Choose the active realm on Overview. A server build with Wildcard support is required;
* **CoA / Wildcard / Warcraft Reborn realms.** Choose the active realm on Overview. A server build supporting the selected realm is required;
the first switch copies world data and creates an empty character database. Accounts are shared, characters and
module settings are separate, and only one world runs. Switching a running server saves characters and restarts it.
The closed client's saved realm follows this selection and is checked again before PLAY. If the client is open,
the change is applied on the next launch through the Manager.
CoA companions are unavailable on Wildcard; other optional modules are experimental. Backups include both realms,
and database updates apply to both.
See [realm profiles and validation](docs/WILDCARD.md).
Bots are unavailable on Wildcard and Warcraft Reborn; other optional modules are experimental. Backups and
database updates include every created realm. Simultaneous startup supports CoA + Wildcard only.
See [realm profiles and validation](docs/WILDCARD.md) and [Warcraft Reborn](docs/WARCRAFT-REBORN.md).
* **Companions (bots).** Fill the world with level-appropriate bots, see progress, stop spawning, take them offline,
despawn N to relieve the server, and choose how many log in at server start.
* **Realmlist switcher.** Keep named realmlists (for example *Solo* and *PTR*) and switch the game client between them from a
@@ -39,17 +43,22 @@ no console, no config files, no database tools. Tauri 2 + Rust + React.
supports LAN, direct and private-network (Tailscale) play, with step-by-step guides and a package to send to friends.
* **Updates to the Manager itself** download in the background and install when you close it. Your servers are never
stopped or changed by a Manager update.
* **Languages:** English, Russian, German, French, Spanish.
* **Languages:** English, Russian, German, French, Spanish, Simplified Chinese.
| Install | Ready |
|---------|-------|
| ![Installing](docs/screenshots/install.png) | ![Ready](docs/screenshots/ready.png) |
## See the Manager
| Overview | Server updates |
|----------|----------------|
| ![Overview](docs/screenshots/overview.png) | ![Updates](docs/screenshots/updates.png) |
| Portable characters (Experimental) | Public realms |
|---|---|
| ![Portable characters](docs/screenshots/portable.png) | ![Public realms](docs/screenshots/realms.png) |
![Backups](docs/screenshots/backups.png)
| Companions | Backups |
|---|---|
| ![Companions](docs/screenshots/bots.png) | ![Backups](docs/screenshots/backups.png) |
The full gallery also covers setup, modules, game clients, playing with friends and making an existing character portable.
[Browse the screenshot gallery](docs/SCREENSHOTS.md).
## Install
@@ -64,9 +73,13 @@ Manager and server updates have separate version histories.
## Status
Phases 0–10 of the plan in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) are done: foundation, import, start/stop,
config engine, backups, clean install from signed packages, updates, companions, client launch, friends, polish.
Remaining work (translation review by native speakers, optional extras) is listed in section 9 of that document. Translation notes: [docs/TRANSLATIONS.md](docs/TRANSLATIONS.md).
**In active development.** Bugs may still occur. If you run into a problem, please [open an issue](https://github.com/Corfirean/coa-server-manager/issues/new/choose).
### Known Limitations
* **Native client login prefill**: Ascension's 3.3.5 client does not accept command-line credentials; users type their password once or link an existing account.
* **Non-Windows SecretStore**: Windows uses DPAPI (`CryptProtectData`) with domain separation entropy. On Linux/macOS, keys fall back to strict 0600 file permissions.
* **Direct to Relay migration**: Established direct TCP sessions cannot migrate mid-stream to Relay; network breaks trigger automatic fallback on the next JOIN.
* **WorkerThreads**: `CharacterDatabase.WorkerThreads` must be set to `1` (the default) for safe remote portable character imports.
## Develop
```
+33 -1
View File
@@ -112,7 +112,14 @@
"Corfirean/coa-server-manager:20261016-preserve-core-migration-history.md",
"Corfirean/coa-server-manager:20261016-shared-auth-migration-history.md",
"Corfirean/coa-server-manager:20261016-update-compatibility-wording.md",
"Corfirean/coa-server-manager:20261018-custom-races-client.md"
"Corfirean/coa-server-manager:20261018-custom-races-client.md",
"Corfirean/coa-server-manager:20261019-portable-stop-diagnostics.md",
"Corfirean/coa-server-manager:20261019-remote-character-class-names.md",
"Corfirean/coa-server-manager:20261020-client-elevation.md",
"Corfirean/coa-server-manager:20261021-custom-races-switching.md",
"Corfirean/coa-server-manager:20261021-portable-experimental.md",
"Corfirean/coa-server-manager:20261021-scaling-health-settings.md",
"Corfirean/coa-server-manager:20261021-warcraft-reborn-realm.md"
],
"releases": [
{
@@ -571,6 +578,31 @@
"Existing client files are preserved when installing or removing race patches"
],
"compare": "https://github.com/Corfirean/coa-server-manager/compare/v0.6.21...v0.6.22"
},
{
"tag": "v0.7.0",
"version": "0.7.0",
"date": "2026-10-21",
"url": "https://github.com/Corfirean/coa-server-manager/releases/tag/v0.7.0",
"notes": [
"Keep portable characters and their saved versions in the Manager, and use them on compatible realms",
"Make an existing character portable from a connected realm",
"Browse public realms and see their connection details",
"Link an existing realm account or create one on hosts that allow it",
"Switch between CoA, Wildcard and Warcraft Reborn realm profiles on supported server builds",
"Adjust creature health for different locations and enemy types in Content Scaling",
"Switch Custom Races patches faster, with visible feedback while changes are applied",
"Handle Windows requests for administrator permission when launching the game"
],
"commit": "d22ff09ac6fd7628aac14d90ec23f547cd9b4bf1",
"experimentalFeatures": [
"portable-characters"
],
"compare": "https://github.com/Corfirean/coa-server-manager/compare/v0.6.22...v0.7.0",
"notice": "Portable transfers into Warcraft Reborn are not supported yet.",
"links": [
"[Player guides and screenshots](https://github.com/Corfirean/coa-server-manager/tree/d22ff09ac6fd7628aac14d90ec23f547cd9b4bf1/docs)"
]
}
]
}
+26
View File
@@ -0,0 +1,26 @@
# Host a CoA server for other players
**Portable characters are experimental.** The feature is in active development and may contain bugs.
## Set up your server
1. Choose **Host a server** on the welcome screen.
2. Choose **Install new server**, or **I already have a server**.
3. Finish setup, then start the server from **Overview**.
4. Link your game client and test joining your server yourself.
## Play with friends
Open **Play with friends**. Use the LAN/private-network instructions for your connection method and run the connectivity checks. Your computer and server must stay on while friends play. Share the connection information prepared by the Manager, never database credentials.
## Let other players find your realm
1. Open **Settings**, then find **Public listing**.
2. Fill in a clear realm name, a short description, language and region.
3. Review the join/account options and connection route.
4. Publish when you are ready to accept players.
5. Check that the realm appears in the browser and ask a friend to test joining from another connection.
A listing makes your server discoverable; it does not move hosting to the cloud or guarantee that your network can be reached. If joining fails, use the connection checks before changing router settings. Portable characters also require a compatible server build and its required settings.
Use **Backups** before changing server versions or optional modules. To stop accepting visitors, turn off the listing; to stop hosting, stop the server.
+43
View File
@@ -0,0 +1,43 @@
# Take your character with you
**Portable characters are experimental.** The feature is in active development and may contain bugs.
Portable characters let you keep a saved character in the Manager and play it on compatible CoA realms.
## Make your first character portable
1. Log out of the character in the game. Keep the Manager open.
2. Open **Characters** and choose **Make an existing character portable**.
3. Select a realm you can access and choose your character.
4. Choose **Make portable**. Your character appears under **Your characters**.
If a character cannot be selected, read the reason beside it. Bot characters, active challenges and some pending rewards can block the operation. Creating the portable copy does not delete the original realm character.
## Make a character from another realm portable
1. Open **Servers** and select the realm where your character lives.
2. Choose **Link an existing account** and enter the account you already use on that realm.
3. Log in to that realm in the game and stay at the character selection screen.
4. Switch back to the Manager with **Alt+Tab** and choose **Show my characters**.
5. Find your character and choose **Make portable**.
6. Wait for the confirmation and the **Portable** badge.
![Link your realm account](screenshots/09-link-realm-account.jpg)
![Choose your character](screenshots/10-remote-portable-candidates.jpg)
![Character saved](screenshots/11-remote-portable-saved.jpg)
## Play your portable character
1. Find a compatible server under **Servers** in player mode, or **Play with Friends** when hosting. You can also use a realm already available to your Manager.
2. Choose your portable character and review compatibility before pressing **Play**.
3. Follow the account prompt. Some hosts create an account for you; others require an existing account.
4. Launch the game when the Manager says the character is ready.
5. Keep the Manager open while playing. Log out and wait for progress to finish saving before closing it or moving to another realm.
A realm with a lower level cap may play your character at a lower level. Check the warning: unsupported content is held back rather than silently discarded. Portable play requires a compatible server; installing the Manager alone does not add support to every server.
## Saved versions and conflicts
Use **Saved versions** to see when progress was saved. If the Manager reports a conflict, follow its explanation before continuing. Avoid playing two copies at once, and keep normal server backups as well.
+41
View File
@@ -0,0 +1,41 @@
# CoA Server Manager 0.7.0
### Your server, a few clicks away
![Your server, a few clicks away](screenshots/setup.png)
### Your server at a glance
![Your server at a glance](screenshots/overview.png)
### Build your own adventuring company
![Build your own adventuring company](screenshots/bots.png)
### Manage your server modules
![Manage your server modules](screenshots/modules.png)
### Your client, ready to play
![Your client, ready to play](screenshots/client.png)
### Keep your progress safe
![Keep your progress safe](screenshots/backups.png)
### Bring your friends along
![Bring your friends along](screenshots/friends.png)
### Find your next realm
![Find your next realm](screenshots/realms.png)
### Portable characters · Experimental
![Portable characters · Experimental](screenshots/portable.png)
### Make a character portable · Experimental
![Make a character portable · Experimental](screenshots/remote-character.png)
+32
View File
@@ -0,0 +1,32 @@
# Warcraft Reborn
Choose **Warcraft Reborn** on Overview to create or switch to this realm. The
installed worldserver must contain Warcraft Reborn support; an old build is
refused before any databases are created. Stop the client before switching to
have its saved realm updated immediately.
The profile uses `CoA.ClassModel = "wcr"`, game-mode mask `0`, live realm type,
and realm ID `3`. Accounts remain in the shared `acore_auth` database. World data
is initially copied from CoA into `acore_world_reborn`; the structure of
`acore_characters` is cloned into `acore_characters_reborn` without copying
players. Existing database names or realm ID 3 block creation.
Settings are stored in `Settings/realm-profiles/reborn.json`. Creating a profile
from Wildcard uses the saved CoA settings as its base, preventing inheritance of
Wildcard gameplay flags. Both bot systems are disabled and cannot be enabled
through this profile; their class mechanics have not been validated. Other
optional modules are marked experimental.
Backups, updates and database checks include every created realm. Restore keeps
using the realm recorded in the recovery point. The Windows launcher is upgraded
from the Manager's previous two-realm patch and routes Warcraft Reborn to its
own databases. Docker uses the same realm schema mapping.
Simultaneous startup continues to support CoA + Wildcard only. Disable that
option before switching to Warcraft Reborn; it cannot be enabled while Warcraft
Reborn is selected.
Automated checks cover profile configuration and restoration, old state files,
binary support detection, database routing, all-realm enumeration, client realm
selection, and upgrading/reversing the launcher patch. These checks do not
constitute a gameplay validation of Warcraft Reborn or optional modules.
Binary file not shown.

After

Width:  |  Height:  |  Size: 62 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 71 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 106 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 82 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 91 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 357 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 492 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 311 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 470 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 459 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 357 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 175 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 352 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 382 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 160 KiB

+88 -38
View File
@@ -32,7 +32,7 @@ def version_key(version):
def eligible(release, component):
pattern = r'v(\d+(?:\.\d+)+)' if component == 'manager' else r'server-(\d+(?:\.\d+)+)'
return not release['draft'] and not release['prerelease'] and re.fullmatch(pattern, release['tag_name'])
return not release['draft'] and re.fullmatch(pattern, release['tag_name'])
def published(repo, component):
@@ -42,7 +42,7 @@ def published(repo, component):
def fragment_note(text, areas):
sections = text.strip().split('---', 2)
sections = text.lstrip('\ufeff').strip().split('---', 2)
if len(sections) != 3 or sections[0]:
raise ValueError('Invalid release fragment')
fields = dict(line.split(':', 1) for line in sections[1].splitlines() if ':' in line)
@@ -58,16 +58,24 @@ def fragment_note(text, areas):
return title
def remote_fragments(repo, sha, seen, areas):
def remote_fragments(repo, sha, seen, areas, excluded_blobs=(), overrides=None):
if not re.fullmatch(r'[0-9a-f]{40}', sha):
raise ValueError('Changelog collection requires an immutable source SHA')
listing = api(f'repos/{repo}/contents/changelog.d?ref={sha}')
files = [f for f in listing if re.fullmatch(r'\d{8}-[a-z0-9-]+\.md', f['name'])]
new = [f for f in files if repo + ':' + f['name'] not in seen]
new = [f for f in files if repo + ':' + f['name'] not in seen and f['sha'] not in excluded_blobs]
def read(item):
reviewed = (overrides or {}).get(repo + ':' + item['sha'])
if reviewed is not None:
if not isinstance(reviewed, str) or not reviewed.strip():
raise ValueError('Reviewed fragment override needs a player-facing title')
return reviewed
blob = api(f'repos/{repo}/git/blobs/{item["sha"]}')
return fragment_note(base64.b64decode(blob['content']).decode('utf-8'), areas)
try:
return fragment_note(base64.b64decode(blob['content']).decode('utf-8'), areas)
except ValueError as error:
raise ValueError(f'{repo}:{item["name"]}@{sha}: {error}') from error
with ThreadPoolExecutor(max_workers=6) as pool:
notes = [note for note in pool.map(read, new) if note]
@@ -86,21 +94,39 @@ def collect_manager(root, tag, seen):
note = fragment_note(text, MANAGER_AREAS)
if note:
notes.append(note)
return notes, [repo + ':' + Path(p).name for p in paths], {'commit': sha}
source = {'commit': sha}
if any('portable' in note.lower() and 'experimental' in note.lower() for note in notes):
source['experimentalFeatures'] = ['portable-characters']
return notes, [repo + ':' + Path(p).name for p in paths], source
def collect_server(repo, tag, seen, previous):
def upstream_fragment_blobs(lock):
upstream = lock['components'].get('upstream')
if not upstream:
return set()
prefix = 'repos/' + upstream['repository'] + '/git/trees/'
tree = api(prefix + upstream['sha'])['tree']
directory = next((item for item in tree if item['path'] == 'changelog.d' and item['type'] == 'tree'), None)
if not directory:
return set()
files = api(prefix + directory['sha'])['tree']
return {item['sha'] for item in files if item['type'] == 'blob' and re.fullmatch(r'\d{8}-[a-z0-9-]+\.md', item['path'])}
def collect_server(repo, tag, seen, previous, overrides=None):
with tempfile.TemporaryDirectory() as folder:
subprocess.run(['gh', 'release', 'download', tag, '--repo', repo, '--pattern', 'release-lock.json', '--dir', folder], check=True)
lock = json.loads((Path(folder) / 'release-lock.json').read_text(encoding='utf-8-sig'))
notes, ids = [], []
imported_blobs = upstream_fragment_blobs(lock)
for role in ('core', 'bots', 'scaling', 'build'):
item = lock['components'].get(role)
if not item:
raise ValueError('Release lock has no ' + role + ' source')
if item['repository'] == 'Corfirean/coa-server-manager':
raise ValueError('A Manager source cannot supply server release notes')
entries, found = remote_fragments(item['repository'], item['sha'], seen, SERVER_AREAS)
entries, found = remote_fragments(item['repository'], item['sha'], seen, SERVER_AREAS,
imported_blobs if role == 'core' else (), overrides)
notes.extend(entries)
ids.extend(found)
old = previous.get('components', {})
@@ -114,16 +140,24 @@ def collect_server(repo, tag, seen, previous):
notes.append(f'Updated {label} to {version}')
if lock['components'].get('upstream', {}).get('sha') != old.get('upstream', {}).get('sha'):
notes.append('Updated the reviewed CoA upstream snapshot')
return list(dict.fromkeys(notes)), ids, {'snapshot': lock['snapshot'], 'components': lock['components']}
return list(dict.fromkeys(notes)), ids, {'snapshot': lock['snapshot'], 'components': lock['components'],
'experimentalFeatures': lock.get('experimentalFeatures', [])}
def notes_md(record):
lines = [f'## {record["version"]} — {record["date"]}', '']
lines.extend('- ' + note.rstrip('.') + '.' for note in record['notes'])
status = ' (Pre-release)' if record.get('prerelease') else ''
lines = [f'## {record["version"]}{status} — {record["date"]}', '']
if record.get('notice'):
lines += [record['notice'], '']
if 'portable-characters' in record.get('experimentalFeatures', []):
lines += ['**Portable Characters are experimental and may contain bugs.**', '']
lines.extend('- ' + note.strip().rstrip('.') + '.' for note in record['notes'])
label = 'Archived release record' if record.get('legacy') else 'Release'
lines += ['', f'[{label}]({record["url"]})']
if record.get('compare'):
lines[-1] += f' · [Source changes]({record["compare"]})'
if record.get('links'):
lines += ['', *(link.strip() for link in record['links'])]
return '\n'.join(lines) + '\n'
@@ -135,7 +169,8 @@ def render(history):
lines = [f'# {title} changelog', '',
('Manager releases only. Updating the Manager does not update the server.' if component == 'manager'
else 'Server packages, companions and server modules only. Manager releases have their own changelog.'),
'', other, '', 'Dates follow GitHub publication (UTC); legacy records retain their archived dates. Newest releases first.', '']
'', other, '', 'Published releases and previews. Pre-release entries do not change the stable update channel.', '',
'Dates follow GitHub publication (UTC); legacy records retain their archived dates. Newest releases first.', '']
for record in sorted(history['releases'], key=lambda r: (r['date'], version_key(r['version'])), reverse=True):
lines.append(notes_md(record))
return '\n'.join(lines).rstrip() + '\n'
@@ -161,6 +196,45 @@ def validate_history(history):
raise ValueError('Server history cannot consume Manager fragments')
def reconcile(history, releases, root):
component, repo = history['component'], history['repository']
records = {r['tag']: r for r in history['releases']}
seen = set(history.get('consumedFragments', []))
for release in releases:
tag = release['tag_name']
preview = bool(release.get('prerelease'))
if tag in records:
record = records[tag]
if preview:
record['prerelease'] = True
elif record.pop('prerelease', False):
seen.update(record.pop('fragments', []))
continue
version = tag.removeprefix('server-').removeprefix('v')
older = [r for r in history['releases'] if not r.get('prerelease')
and version_key(r['version']) < version_key(version)]
previous = max(older, key=lambda r: version_key(r['version']), default={})
if component == 'manager':
notes, ids, source = collect_manager(root, tag, frozenset(seen))
else:
notes, ids, source = collect_server(repo, tag, frozenset(seen), previous,
history.get('fragmentOverrides'))
if not notes:
notes = ['No additional player-facing changes were recorded for this build']
record = {'tag': tag, 'version': version, 'date': release['published_at'][:10],
'url': release['html_url'], 'notes': notes, **source}
if preview:
record.update(prerelease=True, fragments=ids)
else:
seen.update(ids)
if previous.get('tag'):
record['compare'] = f'https://github.com/{repo}/compare/{previous["tag"]}...{tag}'
history['releases'].append(record)
records[tag] = record
history['consumedFragments'] = sorted(seen)
validate_history(history)
def main():
parser = argparse.ArgumentParser()
parser.add_argument('--root', type=Path, default=Path.cwd())
@@ -174,32 +248,8 @@ def main():
component, repo = history['component'], history['repository']
if component not in ('server', 'manager'):
raise ValueError('History must belong to one component')
existing = {r['tag'] for r in history['releases']}
seen = set(history.get('consumedFragments', []))
releases = [] if args.render_only else published(repo, component)
previous = sorted(history['releases'], key=lambda r: (r['date'], version_key(r['version'])))[-1] if existing else {}
for release in releases:
tag = release['tag_name']
if tag in existing:
continue
version = tag.removeprefix('server-').removeprefix('v')
if previous and version_key(version) <= version_key(previous['version']):
raise ValueError('Historical backfill requires a reviewed history correction: ' + tag)
if component == 'manager':
notes, ids, source = collect_manager(args.root, tag, seen)
else:
notes, ids, source = collect_server(repo, tag, seen, previous)
if not notes:
notes = ['Detailed player-facing notes were not recorded; see the source changes for this release']
record = {'tag': tag, 'version': tag.removeprefix('server-').removeprefix('v'),
'date': release['published_at'][:10], 'url': release['html_url'], 'notes': notes, **source}
if previous.get('tag'):
record['compare'] = f'https://github.com/{repo}/compare/{previous["tag"]}...{tag}'
history['releases'].append(record)
seen.update(ids)
previous = record
history['consumedFragments'] = sorted(seen)
validate_history(history)
reconcile(history, releases, args.root)
# Keep a separately reviewed history as the source of truth for historical corrections.
path.write_text(json.dumps(history, indent=2, ensure_ascii=False) + '\n', encoding='utf8', newline='\n')
(args.root / 'CHANGELOG.md').write_text(render(history), encoding='utf8', newline='\n')
@@ -208,7 +258,7 @@ def main():
for record in history['releases']:
release = actual.get(record['tag'])
if not release:
continue # Never create a missing historical release or touch a prerelease.
continue # Never create a missing historical release.
body = notes_md(record)
if (release.get('body') or '').strip() != body.strip():
with tempfile.TemporaryDirectory() as folder:
+96 -2
View File
@@ -28,16 +28,68 @@ class ComponentHistoryTests(unittest.TestCase):
history['releases'][0]['tag'] = 'server-0.6.22'
with self.assertRaises(ValueError): sync.validate_history(history)
def test_unpublished_and_prerelease_tags_never_enter_history(self):
def test_published_previews_are_included_but_drafts_and_other_components_are_not(self):
release = {'tag_name': 'v0.7.0', 'draft': True, 'prerelease': False}
self.assertFalse(sync.eligible(release, 'manager'))
release.update(draft=False, prerelease=True)
self.assertFalse(sync.eligible(release, 'manager'))
self.assertTrue(sync.eligible(release, 'manager'))
release.update(prerelease=False)
self.assertTrue(sync.eligible(release, 'manager'))
self.assertFalse(sync.eligible(release, 'server'))
self.assertFalse(sync.eligible(dict(release, tag_name='stable'), 'server'))
def release(self, version='0.7.0', preview=True):
return {'tag_name': 'v' + version, 'prerelease': preview, 'draft': False,
'published_at': '2026-10-22T12:00:00Z', 'html_url': 'https://example.test/v' + version}
def test_preview_does_not_consume_stable_changes_and_repeated_sync_is_idempotent(self):
history = self.history()
with patch.object(sync, 'collect_manager', return_value=(['Portable Characters are experimental'], ['own:portable'], {'commit': 'a' * 40})) as collect:
sync.reconcile(history, [self.release()], Path('.'))
sync.reconcile(history, [self.release()], Path('.'))
self.assertEqual(collect.call_count, 1)
self.assertEqual(history['consumedFragments'], [])
self.assertEqual(len(history['releases']), 2)
self.assertTrue(history['releases'][-1]['prerelease'])
self.assertIn('## 0.7.0 (Pre-release)', sync.render(history))
def test_promotion_updates_the_same_reviewed_record_without_collecting_or_duplicating(self):
history = self.history()
with patch.object(sync, 'collect_manager', return_value=(['Portable Characters are experimental'], ['own:portable'], {'commit': 'a' * 40})):
sync.reconcile(history, [self.release()], Path('.'))
history['releases'][-1]['notes'] = ['Reviewed player-facing text']
with patch.object(sync, 'collect_manager', side_effect=AssertionError('Frozen notes already recorded')):
sync.reconcile(history, [self.release(preview=False)], Path('.'))
sync.reconcile(history, [self.release(preview=False)], Path('.'))
self.assertEqual(len(history['releases']), 2)
self.assertNotIn('prerelease', history['releases'][-1])
self.assertEqual(history['consumedFragments'], ['own:portable'])
self.assertEqual(history['releases'][-1]['notes'], ['Reviewed player-facing text'])
def test_stable_hotfix_after_higher_preview_keeps_its_own_notes(self):
history = self.history()
with patch.object(sync, 'collect_manager', return_value=(['Shared improvement'], ['own:shared'], {'commit': 'a' * 40})):
sync.reconcile(history, [self.release()], Path('.'))
with patch.object(sync, 'collect_manager', return_value=(['Shared improvement'], ['own:shared'], {'commit': 'b' * 40})) as collect:
sync.reconcile(history, [self.release('0.6.23', preview=False), self.release()], Path('.'))
self.assertEqual(collect.call_args.args[2], set())
hotfix = next(r for r in history['releases'] if r['version'] == '0.6.23')
self.assertEqual(hotfix['notes'], ['Shared improvement'])
self.assertEqual(history['consumedFragments'], ['own:shared'])
def test_server_preview_uses_only_server_locked_sources_and_keeps_notice(self):
history = {'schema': 1, 'component': 'server', 'repository': 'Corfirean/coa-server-build',
'consumedFragments': [], 'releases': []}
release = dict(self.release(), tag_name='server-0.261022.75')
with patch.object(sync, 'collect_server', return_value=(['Experimental Portable Characters support'], ['core:portable'], {'snapshot': 'a' * 64})), \
patch.object(sync, 'collect_manager', side_effect=AssertionError('Wrong component')):
sync.reconcile(history, [release], Path('.'))
history['releases'][0]['notice'] = 'Portable Characters are experimental.'
text = sync.render(history)
self.assertIn('## 0.261022.75 (Pre-release)', text)
self.assertIn('Portable Characters are experimental.', text)
self.assertEqual(history['consumedFragments'], [])
def test_fragment_classification_preserves_source_boundaries(self):
text = '---\narea: manager\ntitle: Updates recover safely\n---\nYour files are preserved.'
self.assertIsNone(sync.fragment_note(text, sync.SERVER_AREAS))
@@ -71,6 +123,41 @@ class ComponentHistoryTests(unittest.TestCase):
seen = {'Corfirean/coa-server-manager:20261021-own.md'}
self.assertEqual(sync.collect_manager(root, 'v0.7.0', seen)[0], [])
def test_utf8_bom_does_not_break_a_valid_historical_fragment(self):
text = '\ufeff---\narea: bots\ntitle: Companions keep their combat form\n---\n'
self.assertEqual(sync.fragment_note(text, sync.SERVER_AREAS), 'Companions keep their combat form')
def test_imported_upstream_fragments_are_not_credited_as_our_changes(self):
import base64
listing = [{'name': '20261021-imported.md', 'sha': 'upstream'}, {'name': '20261021-own.md', 'sha': 'own'}]
body = base64.b64encode(b'---\narea: server\ntitle: Our portable sessions\n---\n').decode()
with patch.object(sync, 'api', side_effect=[listing, {'content': body}]) as calls:
notes, consumed = sync.remote_fragments('owner/core', 'a' * 40, set(), sync.SERVER_AREAS, {'upstream'})
self.assertEqual(notes, ['Our portable sessions'])
self.assertEqual(len(consumed), 2)
self.assertEqual(calls.call_count, 2)
self.assertTrue(calls.call_args.args[0].endswith('/git/blobs/own'))
def test_reviewed_legacy_fragment_override_is_bound_to_exact_blob(self):
import base64
listing = [{'name': '20261006-legacy.md', 'sha': 'legacy-blob'}]
with patch.object(sync, 'api', return_value=listing) as calls:
notes, _ = sync.remote_fragments('owner/core', 'a' * 40, set(), sync.SERVER_AREAS,
overrides={'owner/core:legacy-blob': 'Bots retain their combat form'})
self.assertEqual(notes, ['Bots retain their combat form'])
self.assertEqual(calls.call_count, 1)
with patch.object(sync, 'api', side_effect=[listing, {'content': base64.b64encode(b'Malformed new note').decode()}]):
with self.assertRaisesRegex(ValueError, 'owner/core:20261006-legacy.md'):
sync.remote_fragments('owner/core', 'a' * 40, set(), sync.SERVER_AREAS,
overrides={'owner/core:different-blob': 'Must not hide malformed notes'})
def test_upstream_exclusions_use_the_frozen_source_tree(self):
lock = {'components': {'upstream': {'repository': 'upstream/core', 'sha': 'frozen'}}}
with patch.object(sync, 'api', side_effect=[{'tree': [{'path': 'changelog.d', 'type': 'tree', 'sha': 'notes-tree'}]}, {'tree': [{'path': '20261021-imported.md', 'type': 'blob', 'sha': 'imported'}, {'path': 'README.md', 'type': 'blob', 'sha': 'readme'}]}]) as calls:
self.assertEqual(sync.upstream_fragment_blobs(lock), {'imported'})
self.assertEqual(calls.call_args_list[0].args[0], 'repos/upstream/core/git/trees/frozen')
self.assertEqual(calls.call_args_list[1].args[0], 'repos/upstream/core/git/trees/notes-tree')
def test_render_is_component_scoped_and_stable(self):
text = sync.render(self.history())
self.assertIn('# CoA Server Manager changelog', text)
@@ -78,6 +165,13 @@ class ComponentHistoryTests(unittest.TestCase):
self.assertNotIn('## 0.7.0', text)
self.assertEqual(text, sync.render(self.history()))
def test_reviewed_windows_release_text_renders_without_carriage_returns(self):
record = self.history()['releases'][0]
record.update(notes=['Existing files are preserved\r'], links=['[Guide](https://example.test/guide)\r'])
text = sync.notes_md(record)
self.assertIn('- Existing files are preserved.\n', text)
self.assertNotIn('\r', text)
def test_render_only_does_not_contact_github_or_change_published_history(self):
with tempfile.TemporaryDirectory() as folder:
root = Path(folder); (root / 'changelog').mkdir()