docs: add multiple new metrics (EN + ZH) (#28)

* docs: added activity_details Signed-off-by: neilblaze <[email protected]> * docs: add more metrics Signed-off-by: neilblaze <[email protected]> * doc: add latex support and modify some docs. Signed-off-by: frank-zsy <[email protected]> * docs: updated activity Signed-off-by: neilblaze <[email protected]> * merge: commit `421e67f` into new-metrics-v1 (latest) Signed-off-by: neilblaze <[email protected]> Co-Authored-By: Frank Zhao <[email protected]> * docs: added more metrics (x2) & fixed typos / broken URLs Signed-off-by: neilblaze <[email protected]> Co-Authored-By: Frank Zhao <[email protected]> * docs: update minor changes Signed-off-by: frank-zsy <[email protected]> --------- Signed-off-by: neilblaze <[email protected]> Signed-off-by: frank-zsy <[email protected]> Co-authored-by: frank-zsy <[email protected]>
X-lab2017 · Jul 20, 2024 · e43b981 · e43b981
1 parent 421e67f
commit e43b981
Show file tree

Hide file tree

Showing 22 changed files with 942 additions and 347 deletions.
diff --git a/docs/user_docs/intro.md b/docs/user_docs/intro.md
@@ -45,7 +45,7 @@ OpenDigger 实现的所有指标对所有人开放使用, 您可以通过以下
     </tr>
     <tr>
       <td rowSpan="25">度量</td>
-      <td>Active dates and times</td>
+      <td>Activity dates and times</td>
       <td><a href="https://chaoss.community/metric-activity-dates-and-times/">CHAOSS</a></td>
       <td><a href="https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/active_dates_and_times.json">active_dates_and_times.json</a></td>
       <td><a href="https://github.com/X-lab2017/open-digger/blob/master/src/metrics/chaoss.ts#L1050">Link</a></td>

diff --git a/docs/user_docs/metrics/activity.md b/docs/user_docs/metrics/activity.md
@@ -0,0 +1,53 @@
+# 活跃度
+
+![From](https://img.shields.io/badge/来自-X--lab-blue) ![For](https://img.shields.io/badge/用于-仓库-blue)
+
+## 定义
+
+活跃度（Activity）是由 [X-lab 开放实验室](https://github.com/X-lab2017)定义的一个指标。要全面理解这个指标，您可以参考赵生宇博士发表的[文章](https://my.oschina.net/u/4489239/blog/5290970)。
+
+活跃度是一个统计型指标，其计算方式为：特定开发者在特定仓库上当月的活跃度为该月中该开发者所有各类协作行为的加权和的平方根，即 $ A_u = \sqrt{\sum{w_ic_i}} $ 。而仓库的活跃度即为当月该仓库中所有开发者的活跃度总和，即 $ A_r = \sum{A_u} = \sum_u{\sqrt{\sum{w_ic_i}}} $。
+
+其中 $ c_i $ 为某协作行为的总次数，$ w_i $ 为对应协作行为的权重。根据 [AHP](https://zh.wikipedia.org/zh-cn/%E5%B1%A4%E7%B4%9A%E5%88%86%E6%9E%90%E6%B3%95) 分析的结果，目前将各类行为的权重设置如下：
+
+| 行为 | 提交 Issue | Issue 评论 | 提交 PR | PR Review 评论 | PR 被合入 |
+| --- | --- | --- | --- | --- | --- |
+| 权重 | 2.2235 | 0.5252 | 4.0679 | 0.7427 | 2.0339 |
+
+> 活跃度指标仅考虑对仓库有实质贡献的协作行为，并不考虑如 Star、Fork 等行为，因此这个指标对于识别仓库的活跃程度以及显示最活跃贡献者的历史活跃情况等非常重要。
+
+## 数据
+
+- **链接（基础）：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/activity.json`
+
+- **链接（详情）：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/activity_details.json`
+
+要获取特定仓库的数据，请将 `{platform}`，`{owner}` 和 `{repo}` 替换为实际名称。这里有一个[活跃度示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/activity.json)以及[活跃度详情示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/activity_details.json)。
+
+其中活跃度数据包含该仓库历史的活跃度统计情况，而活跃度详情数据则包含该仓库活跃度的组成情况，即每个开发者在仓库中的活跃度细节。
+
+## 代码
+
+这里是[**实现代码**](https://github.com/X-lab2017/open-digger/blob/master/src/metrics/indices.ts#L185)。
+
+## CodePen 演示
+
+### 活跃度演示
+
+<iframe height="600" scrolling="no" title="OpenDigger - [X-lab] OpenRank/Activity/Bus Factor" src="https://codepen.io/frank-zsy/embed/bGjyqQj?type=activity&default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/frank-zsy/pen/bGjyqQj">
+  OpenDigger - [X-lab] OpenRank/Activity/Bus Factor</a> by Frank Zhao (<a href="https://codepen.io/frank-zsy">@frank-zsy</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+<br/>
+
+### 活跃度详情演示
+
+以下示例已在 [HyperCRX](https://github.com/hypertrons/hypertrons-crx) 中实现，安装 HyperCRX 插件后可以在仓库页面的 Perceptor 标签页中看到该组件。
+
+<iframe height="600" scrolling="no" title="OpenDigger - [X-lab] Project Activity Details" src="https://codepen.io/tyn1998/embed/KKGxVrm?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/tyn1998/pen/KKGxVrm">
+  OpenDigger - [X-lab] Project Activity Details</a> by tyn1998 (<a href="https://codepen.io/tyn1998">@tyn1998</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/user_docs/metrics/activity_dates_and_times.md b/docs/user_docs/metrics/activity_dates_and_times.md
@@ -0,0 +1,29 @@
+# 活动日期和时间 
+
+![From](https://img.shields.io/badge/来自-CHAOSS-blue) ![For](https://img.shields.io/badge/用于-仓库-blue)
+
+## 定义
+
+活动日期和时间 (Activity Dates and Times) 是一个由 [CHAOSS](https://chaoss.community) 定义的指标，有关该指标的详细定义，请参阅 [CHAOSS Metrics - Activity Dates and Times](https://chaoss.community/kb/metric-activity-dates-and-times/)。
+
+该指标有助于确定存储库中单个活动发生的日期和时间戳。它还有助于确定存储库的活动情况以及存储库最活跃的时间。
+
+> 这些数据可用于在时区不是 UTC 的情况下，概率性地估计贡献来自地球上的哪些地区。
+
+## 数据
+
+**链接：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/active_dates_and_times.json`
+
+要获取特定存储库的数据，请将 `{platform}`，`{owner}` 和 `{repo}` 替换为实际名称。这里有一个[示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/active_dates_and_times.json)。
+
+## 代码
+
+这里是[**实现代码**](https://github.com/X-lab2017/open-digger/blob/master/src/metrics/chaoss.ts#L960)。
+
+## CodePen 演示
+
+<iframe height="600" scrolling="no" title="OpenDigger - [CHAOSS]Active dates and times" src="https://codepen.io/frank-zsy/embed/jOpQdZZ?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/frank-zsy/pen/jOpQdZZ">
+  OpenDigger - [CHAOSS]Active dates and times</a> by Frank Zhao (<a href="https://codepen.io/frank-zsy">@frank-zsy</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/user_docs/metrics/bus_factor.md b/docs/user_docs/metrics/bus_factor.md
@@ -1,21 +1,22 @@
-# 巴士系数(Bus Factor)
+# 巴士系数
 
 ![From](https://img.shields.io/badge/来自-CHAOSS-blue) ![For](https://img.shields.io/badge/用于-仓库-blue)
 
 ## 定义
 
-巴士系数，或称为 Contributor Absence Factor，是由 [CHAOSS 社区](https://chaoss.community) 定义的一个指标。有关该指标的详细定义，请参阅 [CHAOSS Metrics - Bus Factor](https://chaoss.community/metric-bus-factor/)。
+巴士系数（Bus Factor），或称为 Contributor Absence Factor，是由 [CHAOSS 社区](https://chaoss.community) 定义的一个指标。有关该指标的详细定义，请参阅 [CHAOSS Metrics - Bus Factor](https://chaoss.community/metric-bus-factor/)。
 
 巴士系数是一个引人注目的指标，因为它形象的表达了一个问题，即：“在项目停滞之前，我们可以失去多少贡献者？”。巴士系数的计算是项目贡献量 50% 的最少人数，并表明了项目失去关键贡献者（包括维护者）后的韧性程度。
 
 > 它有助于识别项目中的工作如何分布在贡献者之间，以及项目中做了大部分工作的关键人物。
 
 ## 数据
 
-- **链接（基础）：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/bus_factor.json`
-- **链接（详细）：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/bus_factor_detail.json`
+**链接（基础）：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/bus_factor.json`
 
-要获取特定仓库的数据，请将`{platform}`、`{owner}`和`{repo}`替换为实际名称。这里有一个[示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/bus_factor.json)。
+**链接（详细）：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/bus_factor_detail.json`
+
+要获取特定仓库的数据，请将`{platform}`、`{owner}` 和 `{repo}` 替换为实际名称。这里有一个[示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/bus_factor.json)。
 
 ## 代码
 

diff --git a/docs/user_docs/metrics/inactive_contributors.md b/docs/user_docs/metrics/inactive_contributors.md
@@ -0,0 +1,29 @@
+# 非活跃贡献者
+
+![From](https://img.shields.io/badge/来自-CHAOSS-blue) ![For](https://img.shields.io/badge/用于-仓库-blue)
+
+## 定义
+
+非活跃贡献者（Inactive Contributors）是由 [CHAOSS](https://chaoss.community) 定义的一个指标，有关该指标的详细定义，请参阅 [CHAOSS Metrics - Inactive Contributors](https://chaoss.community/kb/metric-inactive-contributors/)。
+
+非活跃贡献者是一个指标，显示在特定时间段内已经停止贡献的贡献者数量。决定贡献者被认为非活跃所需的时间段可以由变量决定（默认为 6 个月），并且该指标将显示在给定时间范围内被标记为非活跃的贡献者数量。
+
+> 非活跃贡献者有助于确定有多少人已经停止活跃的贡献。这对于社区经理确定关键成员是否失去兴趣或正在休息是很有用的。
+
+## 数据
+
+**链接：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/inactive_contributors.json`
+
+要获取特定存储库的数据，请将 `{platform}`，`{owner}` 和 `{repo}` 替换为实际名称。这里有一个[示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/inactive_contributors.json)。
+
+## 代码
+
+这里是[**实现代码**](https://github.com/X-lab2017/open-digger/blob/master/src/metrics/chaoss.ts#L880)。
+
+## CodePen 演示
+
+<iframe height="600" scrolling="no" title="OpenDigger - [CHAOSS] Developer Status" src="https://codepen.io/frank-zsy/embed/RwBmpYZ?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/frank-zsy/pen/RwBmpYZ">
+  OpenDigger - [CHAOSS] Developer Status</a> by Frank Zhao (<a href="https://codepen.io/frank-zsy">@frank-zsy</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/user_docs/metrics/issue_resolution_duration.md b/docs/user_docs/metrics/issue_resolution_duration.md
@@ -0,0 +1,29 @@
+# Issue 解决时长
+
+![From](https://img.shields.io/badge/From-CHAOSS-blue) ![For](https://img.shields.io/badge/For-Repo-blue)
+
+## 定义
+
+Issue 解决时长 (Issue Resolution Duration)，也称为 Issue 解决时间 (Time to Issue Resolution)，是一个由 [CHAOSS](https://chaoss.community) 定义的指标，有关该指标的详细定义，请参阅 [CHAOSS Metrics - Time to Issue Resolution](https://chaoss.community/kb/metric-issue-resolution-duration/)。
+
+该指标有助于表明解决问题所需的时间，从问题开启到关闭的平均时间。这个指标可用于确定社区如何快速响应问题以及解决问题所需的时间。
+
+> 对于那些被重新打开并再次关闭的问题，仅最后一个关闭日期对此指标有关联。
+
+## 数据
+
+**链接：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/issue_resolution_duration.json`
+
+要获取特定存储库的数据，请将 `{platform}`，`{owner}` 和 `{repo}` 替换为实际名称。这里有一个[示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/issue_resolution_duration.json)。
+
+## 代码
+
+这里是[**实现代码**](https://github.com/X-lab2017/open-digger/blob/master/src/metrics/chaoss.ts#L292)。
+
+## CodePen 演示
+
+<iframe height="600" scrolling="no" title="OpenDigger - [CHAOSS] Time Duration Related Metrics" src="https://codepen.io/frank-zsy/embed/VwBqwaP?type=issue_resolution_duration&default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/frank-zsy/pen/VwBqwaP">
+  OpenDigger - [CHAOSS] Time Duration Related Metrics</a> by Frank Zhao (<a href="https://codepen.io/frank-zsy">@frank-zsy</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/user_docs/metrics/issue_response_time.md b/docs/user_docs/metrics/issue_response_time.md
@@ -0,0 +1,29 @@
+# Issue 响应时间
+
+![From](https://img.shields.io/badge/来自-CHAOSS-blue) ![For](https://img.shields.io/badge/用于-仓库-blue)
+
+## 定义
+
+Issue 响应时间（Issue Response Time）是由 [CHAOSS](https://chaoss.community) 定义的一个指标，有关该指标的详细定义，请参阅 [CHAOSS Metrics - Issue Response Time](https://chaoss.community/metric-issue-response-time/)。
+
+Issue 响应时间是一个指标，显示从 Issue 开启到来自其他贡献者在该 Issue 上的响应之间经过的时间。
+
+> Issue 响应时间有助于确定社区如何快速响应 Issue。这对于社区经理确定社区是否对 Issue 做出响应和它们被解决的速度是很有用的。高 Issue 响应时间可能表明社区不响应 Issue，而低 Issue 响应时间可能表明社区会及时响应 Issue，这可用于衡量社区的整体活动水平。
+
+## 数据
+
+**链接：** `https://oss.x-lab.info/open_digger/{platform}/{owner}/{repo}/issue_response_time.json`
+
+要获取特定存储库的数据，请将 `{platform}`，`{owner}` 和 `{repo}` 替换为实际名称。这里有一个[示例](https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/issue_response_time.json)。
+
+## 代码
+
+这里是[**实现代码**](https://github.com/X-lab2017/open-digger/blob/master/src/metrics/chaoss.ts#L298)。
+
+## CodePen 演示
+
+<iframe height="600" scrolling="no" title="OpenDigger - [CHAOSS] Time Duration Related Metrics" src="https://codepen.io/frank-zsy/embed/VwBqwaP?type=issue_response_time&default-tab=html%2Cresult" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/frank-zsy/pen/VwBqwaP">
+  OpenDigger - [CHAOSS] Time Duration Related Metrics</a> by Frank Zhao (<a href="https://codepen.io/frank-zsy">@frank-zsy</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
diff --git a/docs/user_docs/metrics/technical_fork.md b/docs/user_docs/metrics/technical_fork.md
@@ -1,10 +1,10 @@
-# 技术分叉(Technical Fork)
+# 技术分叉
 
 ![From](https://img.shields.io/badge/来自-CHAOSS-blue) ![For](https://img.shields.io/badge/用于-仓库-blue)
 
 ## 定义
 
-技术分叉是由 [CHAOSS 社区](https://chaoss.community)定义的一个指标，有关该指标的详细定义，请参阅 [CHAOSS Metrics - Technical Fork](https://chaoss.community/kb/metric-technical-fork/)。
+技术分叉（Technical Fork）是由 [CHAOSS 社区](https://chaoss.community)定义的一个指标，有关该指标的详细定义，请参阅 [CHAOSS Metrics - Technical Fork](https://chaoss.community/kb/metric-technical-fork/)。
 
 技术分叉是仓库的分布式版本控制的副本。技术分叉的数量表示同一代码开发平台上仓库的副本数量。
 

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -5,6 +5,8 @@
 // See: https://docusaurus.io/docs/api/docusaurus-config
 
 import { themes as prismThemes } from 'prism-react-renderer';
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
 
 const defaultLocale = 'zh';
 
@@ -49,12 +51,16 @@ const config = {
           sidebarPath: './sidebars.js',
           editUrl: ({ locale, docPath }) =>
             `https://raw.githubusercontent.com/X-lab2017/open-digger-website/master/${locale === defaultLocale ? 'docs/' : `i18n/${locale}/docusaurus-plugin-content-docs/current/`}${docPath}`,
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
         },
         blog: {
           showReadingTime: true,
           blogSidebarTitle: 'Recent Posts',
           editUrl: ({ blogDirPath, blogPath, locale }) =>
             `https://github.com/X-lab2017/open-digger-website/tree/master/${locale === defaultLocale ? `${blogDirPath}/${blogPath}` : `i18n/${locale}/docusaurus-plugin-content-blog/${blogPath}`}`,
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
@@ -63,6 +69,16 @@ const config = {
     ],
   ],
 
+  stylesheets: [
+    {
+      href: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css',
+      type: 'text/css',
+      integrity:
+        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
+      crossorigin: 'anonymous',
+    },
+  ],
+
   plugins: [
     [
       require.resolve("@easyops-cn/docusaurus-search-local"),

diff --git a/i18n/en/docusaurus-plugin-content-docs/current.json b/i18n/en/docusaurus-plugin-content-docs/current.json
@@ -31,4 +31,4 @@
     "message": "Jupyter Notebook",
     "description": "The label for category jupyter_notebook in sidebar developerDocSidebar"
   }
-}
+}
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/user_docs/intro.md b/i18n/en/docusaurus-plugin-content-docs/current/user_docs/intro.md
@@ -50,7 +50,7 @@ Feel free to use the data to construct your own data application and you can ref
     </tr>
     <tr>
       <td rowSpan="25">Metric</td>
-      <td>Active dates and times</td>
+      <td>Activity dates and times</td>
       <td><a href="https://chaoss.community/metric-activity-dates-and-times/">CHAOSS</a></td>
       <td><a href="https://oss.x-lab.info/open_digger/github/X-lab2017/open-digger/active_dates_and_times.json">active_dates_and_times.json</a></td>
       <td><a href="https://github.com/X-lab2017/open-digger/blob/master/src/metrics/chaoss.ts#L1050">Link</a></td>
-Original file line number
+Diff line change
@@ Expand Up / @@ -31,4 +31,4 @@ @@
         "message": "Jupyter Notebook",
         "description": "The label for category jupyter_notebook in sidebar developerDocSidebar"
       }
-    }
+    }