Skip to content

Commit 31ea013

Browse files
sunshinegsunshineg
authored
Merge pull request #88 from opensourcewin/docs/refresh-multilingual-readmes
docs: refresh multilingual readmes
2 parents 7e8f086 + c3a2c9e commit 31ea013

3 files changed

Lines changed: 308 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 102 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,103 @@
1-
# OpenSource.Win — For Our Shared Future
1+
# OpenSource.Win
22

3-
Static site for OpenSource.Win Manifesto with hacker aesthetic and bilingual EN/zh toggle.
4-
3+
[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
4+
5+
The source for [opensource.win](https://opensource.win): an Astro monorepo for the OpenSource.Win manifesto and the China Open Source HeroRank.
6+
7+
## What is here
8+
9+
- `apps/www` — the OpenSource.Win manifesto landing site.
10+
- `apps/ossheroes` — the China Open Source HeroRank site, including Astro Content Collections for developer profiles and annual rankings.
11+
- `packages/ui` — shared UI components, design tokens, and SEO exports used by both sites.
12+
13+
Both applications are static-first Astro sites. React is used only for selective interactive islands, and Tailwind CSS provides styling. The published site uses clean, file-based routes rather than a hash-routed SPA.
14+
15+
## Prerequisites
16+
17+
- Node.js 20 (the GitHub Actions workflow uses Node 20)
18+
- pnpm 9.15.0 (declared by the root `packageManager` field)
19+
20+
```bash
21+
corepack enable
22+
pnpm --version
23+
```
24+
25+
## Install, develop, build, and preview
26+
27+
```bash
28+
pnpm install --frozen-lockfile
29+
pnpm dev # manifesto app
30+
pnpm --filter ossheroes dev # HeroRank app
31+
pnpm build
32+
pnpm --filter www preview
33+
pnpm --filter ossheroes preview
34+
```
35+
36+
## Verify HeroRank output
37+
38+
The checks read built output; `verify:seo` also reads `apps/www/dist` for the generated sitemap and `llms.txt`.
39+
40+
```bash
41+
pnpm build
42+
pnpm --filter ossheroes verify:urls
43+
pnpm --filter ossheroes verify:seo
44+
```
45+
46+
`verify:urls` checks canonical HeroRank pages and static compatibility redirects. `verify:seo` checks canonical and Open Graph URLs, sampled profile JSON-LD, and the root sitemap and `llms.txt`.
47+
48+
## Public routes
49+
50+
| Route | Purpose |
51+
| --- | --- |
52+
| `/` | OpenSource.Win manifesto landing page |
53+
| `/heroes/` | HeroRank home page |
54+
| `/hero/<login>/` | Developer profile |
55+
| `/heroes/ranking-<year>/` | Annual ranking |
56+
57+
Legacy `/ossheroes/`, `/ossheroes/<login>/`, and `/ossheroes/ranking-<year>/` paths are static redirect pages that preserve query strings and fragments while directing visitors to the canonical routes.
58+
59+
## Project structure
60+
61+
```text
62+
apps/
63+
www/ # manifesto landing site
64+
ossheroes/ # HeroRank app, content, data, and checks
65+
src/content/heroes/<login>/index.md
66+
src/data/rankingList.json
67+
script/ # Node.js ranking/content maintenance scripts
68+
scripts/ # built-output URL and SEO verification scripts
69+
packages/
70+
ui/ # shared UI, tokens, and SEO exports
71+
.github/workflows/
72+
gh-pages.yml # build, verify, merge, and deploy workflow
73+
```
74+
75+
## HeroRank content and data
76+
77+
Developer profiles are Markdown entries in the `heroes` Content Collection at `apps/ossheroes/src/content/heroes/<login>/index.md`. The directory name and `slug` should be the developer's GitHub login.
78+
79+
```md
80+
---
81+
slug: foo
82+
name: Foo
83+
description: Developer location
84+
github_id: 123456
85+
github_avatar: https://avatars.githubusercontent.com/u/123456?v=4
86+
---
87+
88+
Profile text in Markdown.
89+
```
90+
91+
`description` is currently displayed as the developer location. An optional local avatar can sit beside `index.md` and be referenced as `avatar: avatar.png`. Keep contributions focused on the relevant profile; profile and ranking changes are reviewed through pull requests.
92+
93+
Annual rankings are generated from `apps/ossheroes/src/data/rankingList.json`. The Node.js scripts in `apps/ossheroes/script/` support the existing maintenance flow: `sync_xlab.js` refreshes a year from the X-lab source, `update_year_user.js` or `update_all_user.js` enriches GitHub user data (and may require `GITHUB_TOKEN` to avoid API limits), and `front-matter.js` writes those fields into profile Markdown. `enrich-contributions.js` can add primary-contribution repository links to otherwise empty profiles and create pages for its configured new logins; it also uses the GitHub REST API and should be run with `GITHUB_TOKEN`. These scripts determine the target year from the current date where applicable; inspect them and review their data changes before running. When adding a year, also add its compatibility placeholder under `src/content/heroes/opensource-ranking/` as described in [`apps/ossheroes/DEVELOP.md`](apps/ossheroes/DEVELOP.md).
94+
95+
## Deployment
96+
97+
GitHub Actions runs on pushes to `main` and when the `Monthly Script Runner` workflow completes. It installs locked pnpm dependencies, builds both apps, runs the HeroRank URL and SEO checks, merges `apps/www/dist` and `apps/ossheroes/dist` into a single `dist/`, and deploys that directory to the `gh-pages` branch for `opensource.win`.
98+
99+
For another branch, run the local build and checks above, then open a pull request to `main`; deployment follows the merged push. The workflow expects both apps to emit route files at the root of their own output directories, so do not add a site-wide Astro `base` path.
100+
101+
## Contributing
102+
103+
Use pnpm from the repository root, keep changes scoped, and run the relevant build and checks before opening a pull request. Do not commit generated `dist` output unless a change explicitly requires it. For HeroRank profile submissions, change only the applicable content and assets and provide accurate, reviewable information.

‎README.zh-CN.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# OpenSource.Win
2+
3+
[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
4+
5+
[opensource.win](https://opensource.win) 的源代码：一个同时承载 OpenSource.Win 宣言与中国开源码力榜（HeroRank）的 Astro monorepo。
6+
7+
## 项目内容
8+
9+
- `apps/www` — OpenSource.Win 宣言落地页。
10+
- `apps/ossheroes` — 中国开源码力榜站点，包含开发者档案和年度榜单的 Astro Content Collections。
11+
- `packages/ui` — 两个站点共用的 UI 组件、设计 token 与 SEO 导出。
12+
13+
两个应用均采用静态优先的 Astro 构建方式；React 只用于按需加载的交互岛，样式由 Tailwind CSS 提供。发布站点使用清晰的文件路由，不是 hash 路由的 SPA。
14+
15+
## 前置条件
16+
17+
- Node.js 20（GitHub Actions 工作流使用 Node 20）
18+
- pnpm 9.15.0（由根目录 `packageManager` 字段声明）
19+
20+
```bash
21+
corepack enable
22+
pnpm --version
23+
```
24+
25+
## 安装、开发、构建与预览
26+
27+
```bash
28+
pnpm install --frozen-lockfile
29+
pnpm dev # 宣言站点
30+
pnpm --filter ossheroes dev # HeroRank 站点
31+
pnpm build
32+
pnpm --filter www preview
33+
pnpm --filter ossheroes preview
34+
```
35+
36+
## 验证 HeroRank 产物
37+
38+
校验脚本读取构建产物；`verify:seo` 还会读取 `apps/www/dist` 中生成的 sitemap 与 `llms.txt`。
39+
40+
```bash
41+
pnpm build
42+
pnpm --filter ossheroes verify:urls
43+
pnpm --filter ossheroes verify:seo
44+
```
45+
46+
`verify:urls` 校验规范 HeroRank 页面与静态兼容跳转页。`verify:seo` 校验 canonical 与 Open Graph URL、抽样开发者档案的 JSON-LD，以及根 sitemap 和 `llms.txt`。
47+
48+
## 公开路由
49+
50+
| 路由 | 用途 |
51+
| --- | --- |
52+
| `/` | OpenSource.Win 宣言落地页 |
53+
| `/heroes/` | HeroRank 首页 |
54+
| `/hero/<login>/` | 开发者档案 |
55+
| `/heroes/ranking-<year>/` | 年度榜单 |
56+
57+
旧的 `/ossheroes/`、`/ossheroes/<login>/` 与 `/ossheroes/ranking-<year>/` 是静态跳转页：它们会保留 query string 和 fragment，并跳转到规范路由。
58+
59+
## 项目结构
60+
61+
```text
62+
apps/
63+
www/ # 宣言落地站点
64+
ossheroes/ # HeroRank 应用、内容、数据和校验
65+
src/content/heroes/<login>/index.md
66+
src/data/rankingList.json
67+
script/ # Node.js 榜单和内容维护脚本
68+
scripts/ # 构建产物 URL 和 SEO 校验脚本
69+
packages/
70+
ui/ # 共用 UI、token 和 SEO 导出
71+
.github/workflows/
72+
gh-pages.yml # 构建、校验、合并和部署工作流
73+
```
74+
75+
## HeroRank 内容与数据
76+
77+
开发者档案是 `heroes` Content Collection 中的 Markdown 条目，路径为 `apps/ossheroes/src/content/heroes/<login>/index.md`。目录名与 `slug` 应使用开发者的 GitHub login。
78+
79+
```md
80+
---
81+
slug: foo
82+
name: Foo
83+
description: 开发者所在地
84+
github_id: 123456
85+
github_avatar: https://avatars.githubusercontent.com/u/123456?v=4
86+
---
87+
88+
使用 Markdown 撰写个人介绍。
89+
```
90+
91+
`description` 当前展示为开发者所在地。可选的本地头像可与 `index.md` 同目录，并通过 `avatar: avatar.png` 引用。请将贡献限制在对应档案内；档案和榜单改动均通过 Pull Request 审核。
92+
93+
年度榜单由 `apps/ossheroes/src/data/rankingList.json` 生成。`apps/ossheroes/script/` 下的 Node.js 脚本保留既有维护流程：`sync_xlab.js` 从 X-lab 数据源刷新某一年，`update_year_user.js` 或 `update_all_user.js` 补充 GitHub 用户信息（为避免 API 限流可能需要 `GITHUB_TOKEN`），`front-matter.js` 将字段写入档案 Markdown。`enrich-contributions.js` 可为正文为空的档案补充主要贡献仓库链接，并为其配置的新 login 创建页面；它同样使用 GitHub REST API，应在提供 `GITHUB_TOKEN` 时运行。适用时，这些脚本会依据当前日期确定目标年份；运行前请检查脚本，并审阅其数据改动。新增年份时，也须按 [`apps/ossheroes/DEVELOP.md`](apps/ossheroes/DEVELOP.md) 的说明，在 `src/content/heroes/opensource-ranking/` 添加兼容占位文件。
94+
95+
## 部署说明
96+
97+
GitHub Actions 会在推送到 `main` 时，以及 `Monthly Script Runner` 工作流完成时运行。它会安装锁定版本的 pnpm 依赖，构建两个应用，运行 HeroRank URL 和 SEO 校验，将 `apps/www/dist` 与 `apps/ossheroes/dist` 合并为一个 `dist/`，并将该目录部署到 `gh-pages` 分支以服务 `opensource.win`。
98+
99+
其他分支的改动请先在本地运行上面的构建和校验命令，再向 `main` 发起 Pull Request；合并后的推送会触发部署。工作流要求两个应用都将路由文件输出到各自构建目录的根部，因此不要配置全站统一的 Astro `base` 路径。
100+
101+
## 贡献
102+
103+
请在仓库根目录使用 pnpm，保持改动范围清晰，并在提交 Pull Request 前运行相关构建和校验。除非改动明确要求，否则不要提交生成的 `dist` 产物。提交 HeroRank 档案时，只修改相关内容和资源，并提供准确、可审核的信息。

‎README.zh-TW.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# OpenSource.Win
2+
3+
[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
4+
5+
[opensource.win](https://opensource.win) 的原始碼：一個同時承載 OpenSource.Win 宣言與中國開源碼力榜（HeroRank）的 Astro monorepo。
6+
7+
## 專案內容
8+
9+
- `apps/www` — OpenSource.Win 宣言落地頁。
10+
- `apps/ossheroes` — 中國開源碼力榜網站，包含開發者檔案和年度榜單的 Astro Content Collections。
11+
- `packages/ui` — 兩個網站共用的 UI 元件、設計 token 與 SEO 匯出。
12+
13+
兩個應用程式皆採用靜態優先的 Astro 建置方式；React 只用於按需載入的互動 island，樣式由 Tailwind CSS 提供。發布網站使用清楚的檔案路由，不是 hash 路由的 SPA。
14+
15+
## 前置條件
16+
17+
- Node.js 20（GitHub Actions 工作流程使用 Node 20）
18+
- pnpm 9.15.0（由根目錄 `packageManager` 欄位宣告）
19+
20+
```bash
21+
corepack enable
22+
pnpm --version
23+
```
24+
25+
## 安裝、開發、建置與預覽
26+
27+
```bash
28+
pnpm install --frozen-lockfile
29+
pnpm dev # 宣言網站
30+
pnpm --filter ossheroes dev # HeroRank 網站
31+
pnpm build
32+
pnpm --filter www preview
33+
pnpm --filter ossheroes preview
34+
```
35+
36+
## 驗證 HeroRank 產物
37+
38+
檢查指令碼讀取建置產物；`verify:seo` 也會讀取 `apps/www/dist` 中產生的 sitemap 與 `llms.txt`。
39+
40+
```bash
41+
pnpm build
42+
pnpm --filter ossheroes verify:urls
43+
pnpm --filter ossheroes verify:seo
44+
```
45+
46+
`verify:urls` 檢查規範 HeroRank 頁面與靜態相容重新導向頁面。`verify:seo` 檢查 canonical 與 Open Graph URL、抽樣開發者檔案的 JSON-LD，以及根 sitemap 和 `llms.txt`。
47+
48+
## 公開路由
49+
50+
| 路由 | 用途 |
51+
| --- | --- |
52+
| `/` | OpenSource.Win 宣言落地頁 |
53+
| `/heroes/` | HeroRank 首頁 |
54+
| `/hero/<login>/` | 開發者檔案 |
55+
| `/heroes/ranking-<year>/` | 年度榜單 |
56+
57+
舊的 `/ossheroes/`、`/ossheroes/<login>/` 與 `/ossheroes/ranking-<year>/` 是靜態重新導向頁面：它們會保留 query string 和 fragment，並導向規範路由。
58+
59+
## 專案結構
60+
61+
```text
62+
apps/
63+
www/ # 宣言落地網站
64+
ossheroes/ # HeroRank 應用程式、內容、資料和檢查
65+
src/content/heroes/<login>/index.md
66+
src/data/rankingList.json
67+
script/ # Node.js 榜單和內容維護指令碼
68+
scripts/ # 建置產物 URL 和 SEO 檢查指令碼
69+
packages/
70+
ui/ # 共用 UI、token 和 SEO 匯出
71+
.github/workflows/
72+
gh-pages.yml # 建置、檢查、合併和部署工作流程
73+
```
74+
75+
## HeroRank 內容與資料
76+
77+
開發者檔案是 `heroes` Content Collection 中的 Markdown 條目，路徑為 `apps/ossheroes/src/content/heroes/<login>/index.md`。目錄名稱與 `slug` 應使用開發者的 GitHub login。
78+
79+
```md
80+
---
81+
slug: foo
82+
name: Foo
83+
description: 開發者所在地
84+
github_id: 123456
85+
github_avatar: https://avatars.githubusercontent.com/u/123456?v=4
86+
---
87+
88+
使用 Markdown 撰寫個人介紹。
89+
```
90+
91+
`description` 目前顯示為開發者所在地。可選的本機頭像可放在 `index.md` 同一目錄，並以 `avatar: avatar.png` 參照。請將貢獻限定在對應檔案；檔案和榜單變更皆透過 Pull Request 審核。
92+
93+
年度榜單由 `apps/ossheroes/src/data/rankingList.json` 產生。`apps/ossheroes/script/` 下的 Node.js 指令碼保留既有維護流程：`sync_xlab.js` 從 X-lab 資料來源更新某一年，`update_year_user.js` 或 `update_all_user.js` 補充 GitHub 使用者資料（為避免 API 速率限制可能需要 `GITHUB_TOKEN`），`front-matter.js` 將欄位寫入檔案 Markdown。`enrich-contributions.js` 可為正文空白的檔案補充主要貢獻儲存庫連結，並為其設定的新 login 建立頁面；它同樣使用 GitHub REST API，應在提供 `GITHUB_TOKEN` 時執行。適用時，這些指令碼會依目前日期決定目標年份；執行前請檢查指令碼並審閱其資料變更。新增年份時，也須依 [`apps/ossheroes/DEVELOP.md`](apps/ossheroes/DEVELOP.md) 的說明，在 `src/content/heroes/opensource-ranking/` 新增相容佔位檔。
94+
95+
## 部署說明
96+
97+
GitHub Actions 會在推送至 `main` 時，以及 `Monthly Script Runner` 工作流程完成時執行。它會安裝鎖定版本的 pnpm 相依套件，建置兩個應用程式，執行 HeroRank URL 和 SEO 檢查，將 `apps/www/dist` 與 `apps/ossheroes/dist` 合併為一個 `dist/`，並將該目錄部署到 `gh-pages` 分支以服務 `opensource.win`。
98+
99+
其他分支的變更請先在本機執行上述建置和檢查，再向 `main` 建立 Pull Request；合併後的推送會觸發部署。工作流程要求兩個應用程式都將路由檔案輸出到各自建置目錄的根部，因此不要設定全站統一的 Astro `base` 路徑。
100+
101+
## 貢獻
102+
103+
請在儲存庫根目錄使用 pnpm，保持變更範圍清楚，並在建立 Pull Request 前執行相關建置和檢查。除非變更明確需要，否則不要提交產生的 `dist` 產物。提交 HeroRank 檔案時，只修改相關內容和資源，並提供正確、可審核的資訊。

0 commit comments

Comments
 (0)