Skip to content

Commit

Permalink
docs: update global openrank metric doc (#51)
Browse files Browse the repository at this point in the history 
Signed-off-by: frank-zsy <[email protected]>
  • Loading branch information
@frank-zsy
frank-zsy authored Oct 2, 2024
1 parent 43d1b4f commit 1c45606
Show file tree
Hide file tree
Showing 9 changed files with 376 additions and 111 deletions.
8 changes: 4 additions & 4 deletions docs/user_docs/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,28 +27,28 @@ OpenDigger 实现的所有指标对所有人开放使用, OpenDigger 的静态
</thead>
<tbody>
<tr>
<td class="centered-cell"><a href="metrics/openrank/global_openrank"><b>仓库全域 OpenRank</b></a></td>
<td class="centered-cell"><a href="metrics/global_openrank"><b>仓库全域 OpenRank</b></a></td>
<td class="centered-cell"><a href="https://blog.frankzhao.cn/how_to_measure_open_source_2/">X-lab</a></td>
<td class="centered-cell"><a href="https://oss.open-digger.cn/github/X-lab2017/open-digger/openrank.json">openrank.json</a></td>
<td class="centered-cell"><a href="https://github.com/X-lab2017/open-digger/blob/master/src/metrics/indices.ts#L25">链接</a></td>
<td class="centered-cell"><a href="https://codepen.io/frank-zsy/pen/bGjyqQj?type=openrank">Demo</a></td>
</tr>
<tr>
<td class="centered-cell"><a href="metrics/openrank/global_openrank"><b>开发者全域 OpenRank</b></a></td>
<td class="centered-cell"><a href="metrics/global_openrank"><b>开发者全域 OpenRank</b></a></td>
<td class="centered-cell"><a href="https://blog.frankzhao.cn/how_to_measure_open_source_3/">X-lab</a></td>
<td class="centered-cell"><a href="https://oss.open-digger.cn/github/frank-zsy/openrank.json">openrank.json</a></td>
<td class="centered-cell"><a href="https://github.com/X-lab2017/open-digger/blob/master/src/metrics/indices.ts#L57">链接</a></td>
<td class="centered-cell"><a href="https://codepen.io/frank-zsy/pen/bGjyqQj?type=openrank&name=frank-zsy">Demo</a></td>
</tr>
<tr>
<td class="centered-cell"><a href="metrics/openrank/community_openrank"><b>仓库社区 OpenRank</b></a></td>
<td class="centered-cell"><a href="metrics/community_openrank"><b>仓库社区 OpenRank</b></a></td>
<td class="centered-cell"><a href="https://blog.frankzhao.cn/how_to_measure_open_source_3/">X-lab</a></td>
<td class="centered-cell"><a href="https://oss.open-digger.cn/github/X-lab2017/open-digger/community_openrank.json">community_openrank.json</a></td>
<td class="centered-cell"><a href="https://github.com/X-lab2017/open-digger/blob/master/src/metrics/indices.ts#L94">链接</a></td>
<td class="centered-cell"><a href="https://codepen.io/frank-zsy/pen/abjMXBV">Demo</a></td>
</tr>
<tr>
<td class="centered-cell"><a href="metrics/openrank/community_openrank"><b>开发者社区 OpenRank</b></a></td>
<td class="centered-cell"><a href="metrics/community_openrank"><b>开发者社区 OpenRank</b></a></td>
<td class="centered-cell"><a href="https://blog.frankzhao.cn/how_to_measure_open_source_3/">X-lab</a></td>
<td class="centered-cell">-</td>
<td class="centered-cell"><a href="https://github.com/X-lab2017/open-digger/blob/master/src/metrics/indices.ts#L176">链接</a></td>
Expand Down
33 changes: 18 additions & 15 deletions docs/user_docs/metrics/community_openrank.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# 社区 OpenRank
# 社区 OpenRank 贡献度

![From](https://img.shields.io/badge/来自-X--lab-blue) ![For](https://img.shields.io/badge/用于-开发者-blue)

Expand All @@ -8,21 +8,24 @@

与全域 OpenRank 指标的计算方法类似，该算法使用项目内的 Issue、PR 等协作数据来构建网络，其网络模型为：

<br/>

```mermaid
graph TD
classDef rounded rx:5,ry:5;
Developer["开发者\n---------------------\nOpenRank | 数值"]:::rounded
issue["issue\n---------------------\nOpenRank | 数值"]:::rounded
pull_request["pull_request\n---------------------\nOpenRank | 数值"]:::rounded
repo["仓库\n---------------------\nOpenRank | 数值"]:::rounded
Developer -->|活跃| issue
Developer -->|活跃| pull_request
issue -->|属于| repo
pull_request -->|属于| repo
erDiagram
Issue }|--|| Repo: belong
ChangeRequest }|--|| Repo: belong
Developer }|--|{ Issue: activity
Developer }|--|{ ChangeRequest: activity
Repo {
OpenRank number
}
ChangeRequest {
OpenRank number
}
Issue {
OpenRank number
}
Developer {
OpenRank number
}
```

## 代码
Expand Down
42 changes: 23 additions & 19 deletions docs/user_docs/metrics/global_openrank.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,30 @@
# 全域 OpenRank
# 全域 OpenRank 影响力

![From](https://img.shields.io/badge/来自-X--lab-blue) ![For](https://img.shields.io/badge/用于-项目/开发者-blue)

## 定义

全域 OpenRank 是一个由 X-lab 开放实验室提出的开源指标，该指标由赵生宇博士提出，关于全域 OpenRank 的算法细节可以参考[这篇博客](https://blog.frankzhao.cn/how_to_measure_open_source_3)。
全域 OpenRank 影响力是一个由 X-lab 开放实验室提出的开源指标，该指标由赵生宇博士提出，关于全域 OpenRank 影响力的算法细节可以参考[这篇博客](https://blog.frankzhao.cn/how_to_measure_open_source_3)。

全域 OpenRank 是`活跃度`指标的一个下游指标，借鉴了`活跃度`来构建 GitHub 全域项目与开发者之间的一个协作网络，其网络模型是：
全域 OpenRank 影响力是[`活跃度`](./activity)指标的一个下游指标，借鉴了`活跃度`来构建 GitHub 全域项目与开发者之间的一个协作网络，其网络模型是：

<div style={{'text-align':'center'}}>
<embed src="/img/global_openrank.svg?bg_color=lightblue&lang=zh" width="80%" />
</div>

```mermaid
graph TD
classDef rounded rx:5,ry:5;
Developer["开发者\n---------------------\nOpenRank | 数值"]:::rounded
repo["仓库\n---------------------\nOpenRank | 数值"]:::rounded
## 价值主张

Developer --> |活跃| repo
```
<br/>
全域 OpenRank 影响力使用所有全域开发者与仓库的协作关系构建协作网络，并使用 OpenRank 算法进行评价，其基本价值主张是：

在全域 OpenRank 指标的实现中，使用`活跃度`指标作为开发者与仓库之间的边的权重，从而构建出全域协作网络来计算网络中每个节点在每个月的全域 OpenRank 值。但与`活跃度`不同的地方在于，我们并没有对开发者的加权活跃值进行开方运算，这是由于`活跃度`指标中的开方运算是为了将社区参与人数（社区规模）的因素引入到指标计算中，但对于协作网络而言，社区参与人数这个变量已经隐含在了网络结构中。
- 影响力大的项目更容易吸引到更多更有影响力的开发者深度参与。
- 更多的深度参与影响力大的项目会让开发者更有影响力。
- 全域 OpenRank 的计算会部分继承历史数据，从而体现出对于长期主义的重视

与传统 PageRank 不同之处在于，计算中每个节点的全域 OpenRank 值将不仅仅依赖于当月的协作网络结构，并且也部分依赖于该节点在上个月的全域 OpenRank 值。即对于全域协作网络中的每个开发者和仓库节点，会部分的继承其历史的 OpenRank 值，这里也是体现了开源中珍视长期价值的价值观。
## 指标特点

- 由于 OpenRank 是通过协作关系构建的网络指标，相较统计型指标有很强的鲁棒性。即便不做额外处理，如果出现相当比例的数据缺失，OpenRank 依然有很好的平滑性。
- 通过网络关系，可以很好的识别和过滤自动化行为带来的高活跃节点，使得这些节点无法因为高活跃而获得高排名（如 [pddemo](https://github.com/pddemo/demo)）。
- 由于重视长期价值，一些有大量初级开发者参与的学习型仓库并不会获得非常高的排名，因为参与的开发者主要是刚进入开源世界的开发者，而资深开发者则不会深度参与。（如 [first-contributions](https://github.com/firstcontributions/first-contributions)）。

## 代码

Expand All @@ -36,8 +38,10 @@ graph TD

| 参数名 | 值 | 参数描述 | 注 |
| :------------- | :---- | :---------- | :--- |
| OpenRank 默认值 | 1.0 | 协作网中新节点的默认值，例如新加入网络的开发者节点与新仓库 | |
| 开发者继承比例 | 0.5 | 开发者节点对于上个月 OpenRank 的依赖比例 | 该算法认为相较于仓库，开发者的价值更应体现出开源中的长期价值，因此开发者对于历史价值的依赖度较高 |
| 仓库继承比例 | 0.3 | 仓库节点对于上个月 OpenRank 的依赖比例 | |
| OpenRank 衰减系数 | 0.85 | 对于当月不活跃的开发者和仓库节点的 OpenRank 衰减比例 | OpenRank 价值并不会因为开发者或仓库仅在某月不活跃就直接清零 |
| OpenRank 最小值 | 0.1 | 当节点 OpenRank 衰减值该值以下时清空节点 OpenRank | |
| 仓库 OpenRank 默认值 | $0$ | 协作网络中新增仓库节点的默认值 | 该算法认为协作网络中的价值均应来自开发者的活跃，因此仓库节点默认不提供价值 |
| 开发者 OpenRank 默认值 | $0$ | 协作网络中新增开发者节点的默认值 | 该算法认为协作网络中的价值来自开发者活跃，因此开发者默认不提供价值 |
| 开发者 OpenRank 增值 | $min(1,a/88.17)$ | 每次计算时开发者节点的 OpenRank 增值 | 网络中所有价值均来自开发者当月活跃带来的 OpenRank 增值。其中 88.17 为全域开发者每月活跃度分布的 75% 分位数，大于该值则均为 1，小于该值则线性衰减 |
| 开发者继承比例 | $0.5$ | 开发者节点对于上个月 OpenRank 的依赖比例 | 该算法认为相较于仓库，开发者的价值更应体现出开源中的长期价值，因此开发者对于历史价值的依赖度较高 |
| 仓库继承比例 | $0.3$ | 仓库节点对于上个月 OpenRank 的依赖比例 | |
| OpenRank 衰减系数 | $0.85$ | 对于当月不活跃的开发者和仓库节点的 OpenRank 衰减比例 | 所有节点无论是否活跃，均会在当月有一定衰减，从而需要额外的开发者活跃来维持网络价值 |
| OpenRank 最小值 | $1$ | 当节点 OpenRank 衰减至该值以下时清空节点 OpenRank | |
Loading

0 comments on commit 1c45606

Please sign in to comment.