企业官网建设流程全解析

• 文档
• 知识库

本篇技术指南围绕 awesome-java 仓库的官方贡献规范 CONTRIBUTING.md 展开，完整讲解如何向这份精选 Java 框架与库清单提交**项目（Project）与资源（Resource）**两类条目，以及维护者（Maintainer）在聚合多仓库项目时需遵循的元数据规则。读者读完本文将掌握：编辑 README_SOURCE.md 的正确姿势、单条目单 PR 的提交流程、许可证与描述措辞的合规要求，以及由自动化生成器驱动的README.md的排序、计数、Star 与活跃度展示机制。

一、仓库结构与"只编辑源文件"原则

在动手提交前，先厘清这个仓库的两份核心清单文件的分工：

• README_SOURCE.md ——唯一可编辑的数据源。清单的全部项目、资源、分组与描述都定义于此文件顶部注释明确声明："Edit this file, not README.md"。
• README.md ——自动生成的产物。其首行注释写明它由.github/scripts/GenerateReadme.java从README_SOURCE.md生成，内容包含"839 projects · 81 categories · 85 resources"等统计信息，并禁止手工编辑。

因此，贡献者的一切修改都应落在README_SOURCE.md上；生成器负责处理排序、计数、Star 与活跃度，贡献者无需自行运行生成器。仓库根目录的 mise.toml 声明了工具链使用 Temurin JDK，这也与生成器为 Java 程序（GenerateReadme.java）的事实相印证。

二、Suggest a Project：提交一个 Java 项目条目

2.1 条目格式与放置位置

在 README_SOURCE.md 中找到最合适的分类（category），在对应分组下新增一行，并开启一个 Pull Request：

- [Project Name](https://github.com/owner/repository) - A concise, neutral description ending with a period.

要点拆解：

• 链接应指向规范仓库（canonical GitHub repository），即该项目最权威的官方仓库地址；
• 描述必须是简洁、中性的一句话，并以句号结尾（"A concise, neutral description ending with a period."）；
• 若项目存在多个仓库（umbrella 场景），见下文"维护者备注"一节的特殊格式。

2.2 项目的入选标准

CONTRIBUTING.md明确列出候选项目必须满足的硬性条件：

1. Java 是第一公民：项目须将 Java 作为主要 API、运行时、实现目标，或提供实质性的头等集成（first-class integration）；
2. 值得被收录：项目因被广泛推荐、具有创新性、独特性，或填补了某个实用空白而值得注意（noteworthy）；
3. 文档与许可清晰：提供英文文档，并具有明确的许可协议（clear licensing）；
4. 商业项目须透明：若项目为商业产品，须有清晰定价并提供免费档（free tier）。

2.3 许可证徽章（License Chip）规则

仓库会利用 GitHub 的 SPDX 元数据自动为已知许可协议的项目生成许可徽章（chip），因此贡献者不要在描述中重复标注许可证，也不要手工添加 license 或 commercial 徽章。具体规则：

• 已知的 GitHub SPDX 许可证会自动出现，无需人工维护；
• 若某个项目没有可用的 chip（例如无法从 GitHub 元数据获得许可证信息），则必须在条目中主动披露其限制性（restrictive）、非商业（noncommercial）或源码可用（source-available）条款，例如 README_SOURCE.md 中 JADE 条目尾部以(LGPL-2.0-only)形式注明；
• 描述应保持简短、客观，并与同类条目保持区分度（distinctive from similar entries）；
• 只有确实没有更聚焦的分类可放时，才使用Miscellaneous分组。

2.4 提交流程红线

• 先搜索再提交：提交前检索已有条目与历史 issue，避免重复收录（"Search existing entries and issues before submitting."）；
• 自荐同样适用标准：自我推广会被严格审查，但只要项目满足相同标准同样欢迎；
• 一个 PR 只提交一个项目：Use one pull request per project.这是保证评审质量与历史可追溯性的关键约束。

三、Suggest a Resource：提交书籍、播客与社区等资源

资源（Resource）涵盖书籍、播客、人物、社区、相关清单与网站。提交方式与项目类似：在 README_SOURCE.md 中最合适的资源分组下新增一行：

- [Resource Name](https://canonical.example)

可选的描述紧随链接之后：

- [Resource Name](https://canonical.example) - A concise, neutral description ending with punctuation.

资源的硬性要求包括：

• 内容必须当前有效（current）、与 Java 或 JVM 相关；
• 使用规范的 HTTPS 链接（canonical HTTPS link）；
• 契合所选择的分组；
• 涉及行文表述时使用英文；
• 同样要求搜索去重（Search for duplicates）并一个资源一个 PR；
• 贡献者无需运行生成器，排序与展示交由生成流程处理。

四、Maintainer Notes：伞形项目的多仓库元数据

大多数条目直接指向单个 GitHub 仓库。但若某个伞形项目（umbrella project）的 Java 能力确实横跨多个仓库，则需要保留其公开主页，并追加仅供维护者使用的元数据（maintainer-only metadata）：

- [Project](https://example.com) - Description. <!-- github: owner/one, owner/two -->

该 HTML 注释格式的语法为<!-- github: owner/one, owner/two -->，用于声明该项目聚合的仓库列表。生成器对此的解析规则非常严格：

• 至少包含两个规范仓库（Use at least two canonical repositories）；
• 一个仓库只能属于一个条目（A repository may belong to only one entry）；
• 生成器会汇总各仓库的 Star 数（sums their stars）；
• 活跃度取所有仓库中最近一次 push（uses their most recent push for activity）；
• 仅当每个仓库都报告相同的 SPDX 许可证时才展示许可证徽章（shows a license only when every repository reports the same SPDX license）；
• 生成器会拒绝格式错误的元数据、重复使用的仓库以及已归档（archived）的仓库。

以 README_SOURCE.md 中的 Telosys 条目为实例（第 211 行）：

- [Telosys](https://www.telosys.org/) - Java code-generation toolkit with a CLI and model-driven template engine. <!-- github: telosys-tools-bricks/telosys-cli, telosys-tools-bricks/telosys-tools-generator -->

这条真实条目展示了伞形项目如何通过注释元数据将 CLI 与生成器两个仓库聚合为一个条目，供生成器合并统计。

五、许可证条款：贡献者必须知悉的双许可结构

仓库采用双许可结构，贡献者在提交时即同意相应条款：

• 清单与文档类贡献（catalog 与 documentation contributions）：遵循 CC BY-SA 4.0（知识共享-署名-相同方式共享 4.0 国际版）；
• 自动化代码与配置（automation code and configuration）：遵循 MIT License，版权归 Andreas Kull 所有（Copyright (c) 2026）。

对应关系可理解为：README_SOURCE.md这类清单数据归 CC BY-SA 4.0 管辖，而驱动清单生成的自动化代码（如GenerateReadme.java）与仓库配置归 MIT 管辖。这是贡献者在上传条目内容前必须了解的合规前提。

六、从源码与配置印证生成流程

仓库虽只保留清单数据与许可文件，但仍可从现有证据还原其自动化工作流：

• README.md 首行注释直接点明生成器入口.github/scripts/GenerateReadme.java，说明每次合并贡献后，由该 Java 程序从 README_SOURCE.md 重新渲染 README；
• 生成的 README.md 头部包含动态统计（839 projects · 81 categories · 85 resources）与活跃度图例（🟢 pushed within 3 months · 🟠 pushed 3–12 months ago · 🔴 no push for over 12 months），与 CONTRIBUTING 中"generator handles ordering, counts, stars and activity"的表述一一对应；
• mise.toml 将 JDK 固定为 Temurin 发行版，为运行 Java 生成器提供了确定性的工具链前提；
• README_SOURCE.md 顶部注释再次重申编辑约束："Edit this file, not README.md. Project format: - Name - A concise, neutral description ending with punctuation. ... Use absolute HTTPS canonical links and submit one project or resource per pull request."

由此可以推断：贡献流程的本质是"改源文件 → 开 PR → 合并后由生成器自动重排"，贡献者无需本地构建，也无需手工维护 README 中的排序、计数与徽章，这既降低了贡献门槛，也保证了清单展示的一致性。

七、贡献清单速查表

八、常见误区与合规要点

1. 不要编辑 README.md：它由生成器产出，手工改动会在下次生成时被覆盖；
2. 不要重复标注许可证：已知 SPDX 许可由生成器自动出徽章；仅在无 chip 可用时才需在条目内披露受限条款；
3. 不要合并多个条目进一个 PR：one pull request per project/resource是硬性约束；
4. 不要使用非规范链接：项目须指向 canonical GitHub 仓库，资源须使用规范 HTTPS 链接；
5. 伞形项目元数据必须合法：至少两个仓库、仓库不得重复归属、已归档仓库会被拒绝——这些约束由生成器强制校验，格式错误将直接导致生成失败或条目被拒。

通过遵循以上流程，贡献者即可将自己的项目或精选资源合规地加入 awesome-java 这份 Java 生态精选清单，并让后续维护完全交由自动化的生成器接管。

• 文档
• 知识库