release-markdown-fork

Release Markdown Fork

Use this skill for the Zhihu-local Markdown fork release workflow.

Inputs

Required:

• Target version, for example 0.0.1-alpha.N (check it in gradle.properties and compute the next N)
• Fork checkout: /Users/zhaoliyan/IdeaProjects/Zhihu/.tmp/Markdown-zly2006
• Main project checkout: /Users/zhaoliyan/IdeaProjects/Zhihu

Version rule:

• The zly fork has its own 0.0.1-alpha.N release line. When upstream moves to 1.x, do not change the fork's base version to match upstream. Always keep 0.0.1 and only increment the alpha.N suffix.
• A diff against upstream may show VERSION=1.x → VERSION=0.0.1-alpha.N; that is expected for the fork release. Do not "normalize" it back to upstream.
• In gradle.properties, keep a comment immediately above VERSION recording the upstream source version, for example: # Upstream huarangmeng/Markdown version: 1.2.9.
• In commit messages, release notes, and final reports, Original version means this upstream huarangmeng/Markdown source version. It does NOT mean the previous zly2006 fork version. Use Fork version for 0.0.1-alpha.N.

Optional:

• Proxy for Sonatype and repo1 access:
  • https_proxy=http://127.0.0.1:7890
  • http_proxy=http://127.0.0.1:7890
  • all_proxy=socks5://127.0.0.1:7890

Guardrails

• Prefer preserving existing published coordinates. Do not switch the app to Android-only coordinates unless publishing KMP root coordinates is impossible.
• Fork-specific behavior should be reduced to the minimum approved delta. Current approved deltas:
  • NativeBlock support
  • mathFont: MathFont field in MarkdownTheme (font CDN support)
  • Switched latex dependency from io.github.huarangmeng to io.github.zly2006
• Never use destructive git commands on a dirty tree.
• For Zhihu after dependency changes, run:
  1. ./gradlew assembleLiteDebug
  2. ./gradlew ktlintFormat

Dependency order (CRITICAL)

The Markdown fork depends on io.github.zly2006:latex-*. Before publishing Markdown, always verify the latex version it depends on is already published to Maven Central:

# Check what latex version Markdown expects
grep 'latex =' gradle/libs.versions.toml

# Check if that version is on Maven Central
curl -s https://repo1.maven.org/maven2/io/github/zly2006/latex-renderer/maven-metadata.xml | grep '<release>'

If the expected version is NOT on Maven Central, run the release-latex-fork skill first.

Workflow

1. Confirm branch state

In the fork checkout:

• git fetch origin --prune
• git fetch zly --prune
• Confirm origin/master is the upstream head.
• Confirm the release branch contains origin/master:
  • git merge-base --is-ancestor origin/master <release-branch>

If the release branch is ready, fast-forward the fork master branch that tracks zly/master, then push:

• git checkout push-zly-master
• git merge --ff-only <release-branch>
• git push zly push-zly-master:master

Proof to capture:

• git branch -vv
• git log --oneline --decorate --graph --max-count=12 --all

2. Keep only approved fork deltas

Diff against upstream:

• git diff --name-status origin/master...HEAD
• git diff --stat origin/master...HEAD

The intended final diff should be limited to:

• Publishing metadata changes for io.github.zly2006
• Version bump
• A gradle.properties comment recording the upstream huarangmeng/Markdown version the fork release is based on
• NativeBlock parser/renderer support and its tests

3. Publish to Maven Central

Prefer the normal Gradle route first:

• ./gradlew --no-daemon --stacktrace :markdown-parser:publishAndReleaseToMavenCentral
• ./gradlew --no-daemon --stacktrace :markdown-runtime:publishAndReleaseToMavenCentral
• ./gradlew --no-daemon --stacktrace :markdown-renderer:publishAndReleaseToMavenCentral

If Sonatype communication is flaky, export the proxy first.

If a module uploads successfully but Gradle fails while stopping maven-central-build-service, treat the deployment status as the source of truth, not the Gradle exit code.

4. Query deployment status directly

Read mavenCentralUsername and mavenCentralPassword from ~/.gradle/gradle.properties, then query:

• POST https://central.sonatype.com/api/v1/publisher/status?id=<deployment-id>

Use the proxy when needed.

Acceptable states:

• PUBLISHED: release is complete
• PUBLISHING: uploaded and being synced; keep polling
• FAILED: stop and report errors

5. Verify public availability

Check repo1 metadata and artifact URLs:

• curl -s https://repo1.maven.org/maven2/io/github/zly2006/markdown-parser/maven-metadata.xml
• curl -s https://repo1.maven.org/maven2/io/github/zly2006/markdown-runtime/maven-metadata.xml
• curl -s https://repo1.maven.org/maven2/io/github/zly2006/markdown-renderer/maven-metadata.xml

And confirm the exact POMs return 200:

• .../markdown-parser/<version>/markdown-parser-<version>.pom
• .../markdown-runtime/<version>/markdown-runtime-<version>.pom
• .../markdown-renderer/<version>/markdown-renderer-<version>.pom

6. Update Zhihu dependency versions

Edit:

• /Users/zhaoliyan/IdeaProjects/Zhihu/app/build.gradle.kts

Current dependency style is direct Android artifacts:

• implementation("io.github.zly2006:markdown-parser-android:<version>")
• implementation("io.github.zly2006:markdown-renderer-android:<version>")

Update both to the new version.

7. Verify Zhihu

In /Users/zhaoliyan/IdeaProjects/Zhihu run:

• ./gradlew assembleLiteDebug
• ./gradlew ktlintFormat

Collect:

• success/failure
• the dependency lines after edit
• any blocking error if the new release is not yet visible

8. Commit Changes

Then you need to commit the new version. message: build: bump markdown. message body:

Original version: (insert upstream huarangmeng/Markdown version e.g. 1.x.x, NOT the previous fork version)
Fork version: (insert fork version e.g. 0.0.1-alpha.N)

DO NOT PUSH!

Failure handling

Sonatype upload hangs without returning deployment ID

• Retry with the proxy exported.
• Prefer direct Sonatype Publisher API upload of the generated bundle under build/publish/*.zip when Gradle upload is unstable.

Gradle fails with maven-central-build-service

• Query the deployment status API.
• If status is PUBLISHED or PUBLISHING, do not re-version immediately.
• Only bump to a new alpha if Sonatype shows FAILED or the version never created a deployment.

renderer lags while parser and runtime are already published

• Keep coordinates unchanged.
• Poll deployment status until PUBLISHED.
• Only update Zhihu after the renderer root artifact or Android artifact is publicly reachable.

Fresh LaTeX version is public but Gradle still cannot resolve it

• Symptom: repo1/repo.maven artifact URLs for io.github.zly2006:latex-*:<version> return 200, but Markdown Gradle tasks still fail with Could not find io.github.zly2006:latex-renderer:<version>.
• Cause: Gradle may retain a negative resolution/configuration-cache result from the window before Maven Central fully propagated the new LaTeX release.
• Fix: rerun the Markdown verification or publish command with both dependency refresh and configuration cache disabled:

./gradlew --no-daemon --no-configuration-cache --refresh-dependencies <task>

• Do not re-version or republish LaTeX when direct Maven artifact checks are already 200; treat this as local Gradle cache state unless the fresh command still fails with a non-cache error.

Version line accidentally follows upstream

• Symptom: after rebasing/branching from the latest upstream tag, the release version is treated as if it should follow upstream's 1.x line.
• Cause: confusing "merge latest upstream" with "adopt upstream's published version family".
• Fix: keep the fork identity stable. For this fork, the public version line remains 0.0.1-alpha.N; the release task is to advance N, not to rename the series.

Final report checklist

• Fork master commit and push proof
• Diff summary vs origin/master
• Deployment IDs and Sonatype states
• Public Maven coordinates
• Repo1 availability proof
• Zhihu dependency update proof
• assembleLiteDebug result
• ktlintFormat result