Developer Guide

This guide is for developers who contribute to, maintain, or review ECHO Page. ECHO Page hosts the ECHO Next official website, documentation, changelog, and static update feed, so changes should prioritize site stability, accurate release information, and reliable download paths.

Project Scope

ECHO Page primarily maintains:

The homepage, download pages, changelog pages, and documentation site.
Version notes under src/content/releases.
Static update feed files under public/update.
Documentation content, product images, brand assets, and required deployment scripts.

Do not publish desktop-app implementation details, temporary test notes, experimental planning drafts, or unconfirmed release promises as formal site content. Public pages should only present information that is confirmed, maintainable, and safe for users to rely on.

Commit And PR Rules

Prefer small, clear PRs. A PR should be explainable in one sentence and should usually touch one category of files, such as documentation only, release notes only, or download-page logic only.

Any large PR must contact me first, otherwise it will be directly rejected.

These changes usually count as large PRs:

Changing site structure, styling systems, release scripts, and content data at the same time.
Rewriting the homepage, download page, docs navigation, or update-feed generation logic.
Introducing a new framework, build plugin, third-party service, or deployment flow.
Migrating large documentation sets, deleting content in bulk, or reshaping public navigation.
Affecting downloads, auto updates, SEO, language routing, or build output.

If you are not sure whether a change is a large PR, treat it as one and share the goal, scope, risks, and plan before implementation.

Development Requirements

Check the working tree before making changes so you do not overwrite work from another developer or process. Only touch the files required for your task; if you see unrelated edits, do not revert them and do not fold them into your PR.

Content changes should stay readable, maintainable, and verifiable:

Keep Chinese and English pages aligned when the page exists in both languages.
Release notes must match the real version, artifacts, and update feed.
External links, download links, GitHub Release links, and mirror notes must be accurate.
Images should have a clear purpose and should not add unnecessary weight.
Document titles, sidebar labels, and paths should stay short and stable.

Code and style changes should follow the existing Astro, Starlight, component, and CSS structure. Avoid adding new abstractions, global style layers, or complex runtime logic unless the benefit is clear.

High-Risk Changes

Be especially careful with changes that:

Modify astro.config.mjs, deployment scripts, domains, language routing, or sitemap behavior.
Modify scripts/generate-update-feed.mjs, public/update, or auto-update files.
Change download artifact selection, version sorting, or GitHub Release sync logic.
Reshape documentation information architecture, navigation levels, or public entry points.
Delete docs, images, download assets, or historical release records.

If a change could stop users from downloading, auto-updating, or seeing correct version information, confirm it with the maintainer first.

Validation Principles

Validation should be efficient. Do not spend a long time on low-value tests just for formality. Choose the smallest proof that still covers the changed behavior:

For Markdown-only edits, check the page path, title, links, and frontmatter.
For release-note edits, run content validation and confirm version, date, and artifact fields.
For update-feed or download logic, verify the generated output and key download entry points.
For Astro components, routes, or styles, run at least a local build or inspect the affected pages in a browser.

If you do not run a full build or full test pass, say why in the PR and list the targeted validation that was completed.

PR Description Checklist

A PR description should include:

What problem the change solves.
Which files or pages changed.
What validation was run.
Any risk, rollback path, or maintainer confirmation needed.

Owning the quality of public content matters more than making a PR large. Keep the scope clear, the behavior verifiable, and the risk explainable.