6.1 贡献指南与参与方式

LEANN 从一个人维护的仓库，长成社区项目

在体系收尾的第一站，我们谈「怎么加入」。开源项目的健康度，不取决于核心开发者多强，而取决于新人能否在半小时内送出第一个有效贡献。

我们建议贡献从「文档与复现」起步，而不是一上来改核心。下面给出一段贡献者自检，确保本地能复现基准后再提改动。

def contributor_checklist():
    steps = [
        'fork 并 clone 仓库',
        '按 README 自检环境（详见第3章）',
        '运行基准脚本确认数值一致',
        '在分支上改动并补测试',
        '提交 PR 描述动机与验证',
    ]
    return steps

for i, s in enumerate(contributor_checklist(), 1):
    print(f'{i}. {s}')
​

这段清单的取向是「先能复现，再谈改动」。我们见过太多 PR 因为本地环境不同导致基准对不上， reviewer 根本没法验。

PR 的协作也有工程规范。下面用一段极简的变更分类，帮助贡献者把改动说清楚，便于评审。

def classify_change(files):
    if any(f.startswith('test') for f in files):
        return '含测试，优先评审'
    if any(f.endswith('.md') for f in files):
        return '文档为主，轻量评审'
    return '代码改动，需完整验证'

print(classify_change(['leann/core.py', 'test_core.py']))
​

案例：第一个文档 PR

• 背景：新人不熟核心，想贡献却不敢动代码。
• 操作：按清单从「补一段缺失的 API 示例」入手，跑通基准后提 PR。
• 结果：PR 当天合并，新人建立信心，后续开始修小 bug。
• 解读：降低首贡献门槛，比招核心开发者更能撑起社区活跃度。
• 变式：可设 good-first-issue 标签，把适合新人的任务显式标出来。

贡献要可持续，得有评审节奏。一个人维护时，PR 积压会让贡献者热情冷却。下面给出一段按标签分流的评审优先级，让维护者先处理「能快速合」的，再啃大的。

def triage(prs):
    order = sorted(prs, key=lambda p: (
        0 if p['label'] == 'good-first-issue' else 1,
        0 if p['has_test'] else 1,
    ))
    return [p['id'] for p in order]

print(triage([
    {'id': 'A', 'label': 'feature', 'has_test': False},
    {'id': 'B', 'label': 'good-first-issue', 'has_test': True},
]))
​

「good-first-issue」标签是社区增长的杠杆：把边界清晰、风险低、能独立验证的任务显式标出来，新人能在不被 intimidate 的情况下完成首贡献。我们建议每个大特性都顺手拆一个这样的小任务放出。

回到全册，贡献指南不是终点而是回路：你今天的用法、踩的坑、补的文档，正是下一版教程的原料。轻量神经架构能长起来，靠的是这种「用的人也在写的人」的飞轮。

参与贡献还有一条隐性回报：你踩的坑会变成别人的捷径。开源项目最稀缺的不是写代码的人，而是愿意把「这里有个坑」写进文档的人。我们鼓励贡献者顺手补一段「我卡了三小时的地方」，这种朴素记录往往比漂亮的设计文档更救新人。LEANN 的文档仓库和代码仓库同源评审，正是为了让踩坑记录能和被它修掉的代码一起合并。

最后说一句长期的视角。轻量神经架构这类项目，生命力来自「用的人也是写的人」这个飞轮：你今天用它解决了边缘端的问题，明天把解法贡献回去，后别人又站在你的肩膀上。社区不是代码托管地，而是把分散在各行业里的工程智慧汇流的地方。到这，全册六章走完，愿你既能独立搭出原型，也愿意把下一次踩坑记下来。

贡献者最需要的反馈是「被看见」。一个 PR 提交后石沉大海，比被拒绝更伤士气。我们建议维护者给每个 PR 一个明确状态：接受、需改、或说明暂不接纳的理由。哪怕只是「这思路和当前方向不合，但我们感谢」，也比沉默强。社区的温度，往往藏在这些小回应里。

文档贡献也该被同等认可。很多项目把文档当二等公民，导致示例陈旧、坑点无人记。我们主张文档 PR 和代码 PR 走同一套评审与致谢流程，甚至设专项奖励，因为对轻量神经架构这种重落地的项目，一份好文档的杠杆可能高过一行核心代码。还有一类贡献常被忽视：负向反馈。你告诉维护者「我在某设备上限了三天」，这比「项目真棒」有价值得多。健康的社区会把失败用例当宝贝收集，因为每一个失败都是下一版要补的边界。

最后，贡献的终点是你也成为维护者。好的开源项目都有清晰的「从使用者到提交者到维护者」的路径，让活跃贡献者自然接棒。LEANN 把这称为「把飞轮交给后来人」：当使用者陆续变成写作者，项目就不再依赖某一个英雄，而是拥有自我延续的生命。我们鼓励每个人从最小的一步开始：改一个错别字、补一句缺失的说明、跑通一个示例并记下卡点。这些看似微不足道，却是飞轮最初的那一下推力，等你回头，会发现自己已经在这条路上走了很远，而项目也因你这一下的推力，转得比昨天更稳。

社区里还有一种 invisible 的贡献，叫「守夜人」：有人长期在 issue 里回答新人问题、把重复提问整理成 FAQ、在版本发布时写清晰的变更说明。这些事不显眼，却是让项目「可进入」的关键。我们建议每个项目都公开感谢这类守夜人，因为留住他们，比吸引十个一次性贡献者更能决定社区的寿命。开源的可持续，靠的从来不是峰值热度，而是日常的那点温度。

说到底，社区是一种长期关系，不是一次活动。很多项目开局热闹，半年后沉寂，问题往往出在只重「拉新」不重「留住」。留住贡献者的，从来不是口号，而是「我提的东西有人接、我踩的坑有人改、我待着舒服」。把这些看似柔软的感受落成具体的流程——及时回应、认可多样贡献、清晰路径——社区才有自生长的力量。

本节可考核点：能说出「先复现再改动」为何重要，并解释降低首贡献门槛对社区健康的意义。