📦 Release Guide / 发布指南 • Jiaxin的仓库

This guide explains how to release a new version of your NPM package to NPM and GitHub.

本指南说明如何将你的 NPM 包的新版本发布到 NPM 和 GitHub。

Prerequisites / 前提条件

1. GitHub Repository Secrets / GitHub 仓库密钥

You need to configure two secrets in your GitHub repository:

你需要在 GitHub 仓库中配置两个密钥：

NPM_TOKEN - NPM 访问令牌

Go to npmjs.com → Your Profile → Access Tokens
Create a new Automation token (or Publish token)
Copy the token
Go to your GitHub repo → Settings → Secrets and variables → Actions
Create new secret: NPM_TOKEN with your token value

GH_TOKEN - GitHub 个人访问令牌

Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Generate new token with repo and write:packages permissions
Copy the token
Go to your GitHub repo → Settings → Secrets and variables → Actions
Create new secret: GH_TOKEN with your token value

Note: You can also use the default GITHUB_TOKEN, but GH_TOKEN is recommended for more permissions.

Release Steps / 发布步骤

Step 1: Update Version / 更新版本号

Update the version in package.json:

更新 package.json 中的版本号：

# For the first release / 首次发布

npm version 0.1.0



# For subsequent releases / 后续发布

npm version patch # 0.1.0 -> 0.1.1 (bug fixes / 错误修复)

npm version minor # 0.1.0 -> 0.2.0 (new features / 新功能)

npm version major # 0.1.0 -> 1.0.0 (breaking changes / 重大变更)

Step 2: Update CHANGELOG / 更新更新日志

Edit CHANGELOG.md and move items from [Unreleased] to a new version section:

编辑 CHANGELOG.md，将 [Unreleased] 部分的内容移到新的版本部分：

## [0.1.0] - xxxx-xx-xx



### Added

- Initial release of your-package-name

- Feature 1

- Feature 2

- ... (all your features)



## [Unreleased]



(留空或添加下一个版本的计划)

Step 3: Commit Changes / 提交更改

git add package.json CHANGELOG.md

git commit -m "chore: release v0.1.0"

git push origin main

Step 4: Create and Push Tag / 创建并推送标签

# Create a tag (this triggers the release workflow)

# 创建标签（这将触发发布工作流）

git tag v0.1.0



# Push the tag to GitHub

# 推送标签到 GitHub

git push origin v0.1.0

Step 5: Wait for GitHub Actions / 等待 GitHub Actions

Once you push the tag, GitHub Actions will automatically:

推送标签后，GitHub Actions 会自动：

✅ Run tests and build / 运行测试和构建
✅ Create a GitHub Release / 创建 GitHub Release
✅ Publish to NPM / 发布到 NPM

You can monitor the progress at:

你可以在以下位置监控进度：

https://github.com/YOUR_USERNAME/your-repo-name/actions

Manual Release (if needed) / 手动发布（如需要）

If the automatic release fails, you can publish manually:

如果自动发布失败，你可以手动发布：

Manual NPM Publish / 手动发布到 NPM

# Login to NPM (first time only)

# 登录 NPM（仅首次）

npm login



# Publish to NPM

# 发布到 NPM

npm publish --access public

Manual GitHub Release / 手动创建 GitHub Release

Go to: https://github.com/YOUR_USERNAME/your-repo-name/releases/new
Choose your tag: v0.1.0
Write release notes (copy from CHANGELOG.md)
Click “Publish release”

Version Numbering Guide / 版本号指南

Follow Semantic Versioning:

遵循语义化版本：

MAJOR (1.0.0 → 2.0.0): Breaking changes / 不兼容的 API 修改
Example: Changing component props, removing layouts
示例：更改组件属性、删除布局
MINOR (0.1.0 → 0.2.0): New features (backward compatible) / 新功能（向后兼容）
Example: Adding new layouts, new components
示例：添加新布局、新组件
PATCH (0.1.0 → 0.1.1): Bug fixes / 错误修复
Example: Fixing styling issues, fixing auto-numbering
示例：修复样式问题、修复自动编号

Quick Release Checklist / 快速发布检查清单

Before releasing, make sure:

发布前确保：

Complete Release Command Sequence / 完整发布命令序列

Here’s a complete example for your first release (v0.1.0):

这是首次发布 (v0.1.0) 的完整示例：

# 1. Update version

npm version 0.1.0



# 2. Update CHANGELOG.md (manually edit the file)

# 编辑 CHANGELOG.md 文件



# 3. Commit changes

git add package.json package-lock.json CHANGELOG.md

git commit -m "chore: release v0.1.0"



# 4. Push to main

git push origin main



# 5. Create and push tag

git tag v0.1.0

git push origin v0.1.0



# 6. Wait for GitHub Actions to complete

# GitHub Actions will automatically:

# - Create GitHub Release

# - Publish to NPM

Verify Release / 验证发布

After the release completes, verify:

发布完成后，验证：

1. Check NPM / 检查 NPM

# Check if package is available

npm view your-package-name



# Try installing it

npm install your-package-name

Or visit: https://www.npmjs.com/package/your-package-name

2. Check GitHub Release / 检查 GitHub Release

Visit: https://github.com/YOUR_USERNAME/your-repo-name/releases

You should see your release with:

Release notes from CHANGELOG.md
Attached build artifacts (if any)

Troubleshooting / 故障排除

Release workflow failed / 发布工作流失败

Check GitHub Actions logs: https://github.com/YOUR_USERNAME/your-repo-name/actions
Common issues:

Missing NPM_TOKEN or GH_TOKEN secrets
Invalid token permissions
Version already exists on NPM
Build errors

NPM publish failed / NPM 发布失败

# Check your login status

npm whoami



# Re-login if needed

npm logout

npm login



# Try publishing again

npm publish --access public

Tag already exists / 标签已存在

# Delete local tag

git tag -d v0.1.0



# Delete remote tag

git push origin --delete v0.1.0



# Recreate tag

git tag v0.1.0

git push origin v0.1.0

Post-Release / 发布后

After successful release:

成功发布后：

✅ Announce on social media / 在社交媒体上宣布
✅ Update documentation site (if any) / 更新文档站点（如有）
✅ Close related issues / 关闭相关问题
✅ Start planning next release / 开始规划下一个版本

Need Help? / 需要帮助？

📖 NPM Publishing Guide: https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry
📖 GitHub Releases Guide: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository
📖 Semantic Versioning: https://semver.org/

Happy Releasing! / 发布愉快！ 🚀

5. Automatic Release

The GitHub Action will automatically:

Build the project
Create a GitHub Release with changelog
Publish to NPM registry

Manual Release (Alternative)

If you need to publish manually:

# Login to NPM

npm login



# Publish

npm publish --access public

Version Guidelines

Follow Semantic Versioning:

MAJOR (x.0.0): Breaking changes
MINOR (0.x.0): New features, backwards compatible
PATCH (0.0.x): Bug fixes, backwards compatible

Verify Release

After release:

Check NPM: https://www.npmjs.com/package/your-package-name
Check GitHub Releases: https://github.com/YOUR_USERNAME/your-repo-name/releases
Test installation: npm install your-package-name

Troubleshooting

NPM Publish Failed

Verify NPM_TOKEN is correctly set in GitHub Secrets
Ensure package version hasn’t been published before
Check if you have publish permissions for the package

GitHub Release Failed

Verify GITHUB_TOKEN permissions (should be automatic)
Check workflow logs in Actions tab

Build Failed

Ensure all dependencies are in package.json
Test build locally: npm run build