kup-cli 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +70 -67
  2. package/README.zh.md +150 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,3 +1,5 @@
1
+ English | [中文](README.zh.md)
2
+
1
3
  # Kup
2
4
 
3
5
  <img src="https://user-images.githubusercontent.com/1231359/171321963-e8e73bdf-f9c8-435b-9707-318e92f1805a.png" width="150" height="80" align="right" alt="Kup logo">
@@ -6,135 +8,136 @@
6
8
  >
7
9
  > 这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。
8
10
 
9
- ## 谁需要它
11
+ ## Who Is It For
10
12
 
11
- * 利用 GitHub issue 写博客的作者们，可以方便地在本地编辑原稿，并随时发布新博文或更新已有博文。
12
- * 通过 GitHub issue 发布文档的开源软件作者们，可以把代码仓库中的文档更新到指定 issue。
13
- * 其它需要频繁更新 GitHub issue 的人。
13
+ * Bloggers who publish with GitHub issues and want to edit drafts locally, then publish new posts or update existing ones at any time.
14
+ * Open-source authors who publish documentation through GitHub issues and want to sync docs from the repository to specific issues.
15
+ * Anyone else who needs to update GitHub issues frequently.
14
16
 
15
17
 
16
- ## 安装
18
+ ## Installation
17
19
 
18
- 需要全局安装，以便随时在命令行调用：
20
+ Install it globally so you can call it from the command line at any time:
19
21
 
20
22
  ```sh
21
- npm i -g kup-cli
23
+ npm install -g kup-cli
22
24
  ```
23
25
 
24
- （当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）
26
+ (When a new version of Kup is released, run the same command again to upgrade.)
25
27
 
26
28
 
27
- ## 使用方法
29
+ ## Usage
28
30
 
29
- ### 发布新 issue
31
+ ### Publish a New Issue
30
32
 
31
33
  ```sh
32
34
  kup ./path/to/file.md --repo foo/bar
33
35
  ```
34
36
 
35
- Kup 会把 `file.md` 文件的内容发布为 `foo/bar` 仓库的一个新 issue，发布成功后会告知新 issue 的编号。
37
+ Kup will publish the content of `file.md` as a new issue in the `foo/bar` repository, and report the new issue number after it succeeds.
36
38
 
37
- ### 更新已有 issue
39
+ ### Update an Existing Issue
38
40
 
39
41
  ```sh
40
42
  kup ./path/to/file.md --repo foo/bar --id 123
41
43
  ```
42
44
 
43
- Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123` 的 issue。
45
+ Kup will update issue `123` in the `foo/bar` repository with the content of `file.md`.
44
46
 
45
- ### 准备工作
47
+ ### Preparation
46
48
 
47
- 操作 GitHub issue 是需要权限认证的，因此你需要向 Kup 提供 GitHub token，以便 Kup 调用 GitHub API。
49
+ Updating GitHub issues requires authentication, so you need to provide a GitHub token for Kup to call the GitHub API.
48
50
 
49
- 1. 在 GitHub 的 “[Personal access tokens](https://github.com/settings/tokens)” 页面生成一个新 token，权限范围需要选中 “repo”。（详细说明参见 [这篇文档](https://github.com/cssmagic/kup/issues/17)。）
51
+ 1. Create a new token on GitHub's "[Personal access tokens](https://github.com/settings/tokens)" page, and make sure the `repo` scope is selected. (See [this document](https://github.com/cssmagic/kup/issues/17) for details.)
50
52
 
51
- 2. 把获取到的 token 写入环境变量：
53
+ 2. Put the token into an environment variable:
52
54
 
53
- ```sh
54
- export GITHUB_TOKEN=ghp_**********
55
- ```
55
+ ```sh
56
+ export GITHUB_TOKEN=ghp_**********
57
+ ```
56
58
 
57
- 如果 Kup 未能从环境变量获取 token，会在命令行向你询问。
59
+ If Kup cannot read a token from the environment, it will prompt you for one in the terminal.
58
60
 
59
61
 
60
- ## 命令行参数
62
+ ## Command-Line Options
61
63
 
62
- 参数 | 短名 | 值类型 | 含义 | 备注
64
+ Option | Short | Value Type | Description | Notes
63
65
  ---|---|---|---|---
64
- `--repo` | `-r` | 字符串 | 指定 GitHub 仓库
65
- `--id` | `-i` | 整数 | 指定 issue 的编号 | <li>指定编号表示更新已有 issue<li>未指定编号则表示发布新 issue
66
- `--version` | `-v` | - | 显示版本号
67
- `--help` | `-h` | - | 显示帮助信息
66
+ `--repo` | `-r` | string | Specify the GitHub repository
67
+ `--id` | `-i` | integer | Specify the issue number | <ul><li>Providing a number means updating an existing issue<li>Omitting it means publishing a new issue</ul>
68
+ `--version` | `-v` | - | Show the version number
69
+ `--help` | `-h` | - | Show help information
68
70
 
69
71
 
70
- ## 进阶
72
+ ## Advanced
71
73
 
72
- ### 如何更方便地指定 `repo` 参数？
74
+ ### How can I specify the `repo` option more conveniently?
73
75
 
74
- 有以下方式可以指定 `repo` 参数，优先级递减：
76
+ Kup can determine the `repo` option in the following order of priority:
75
77
 
76
- 1. 调用命令行时指定的 `--repo` 参数。
77
- 1. Markdown 文件内的 [元数据](https://github.com/cssmagic/kup/issues/1) 的 `repo` 字段。
78
- 1. 当前项目的 `package.json` 文件内的 `kup.repo` 字段。Kup 会以 Markdown 文件所在目录为起点逐级向上寻找 `package.json` 文件。
79
- 1. 如果 `package.json` 文件内没有 `kup.repo` 字段，则 Kup 会尝试根据 `repository` 字段来猜测仓库名（在使用前会向用户确认）。
80
- 1. 如果以上方式都没有成功，则 Kup 会继续查找同级或上级目录中的 `.git/config` 文件，并尝试根据其中 `remote "origin"` 的 `url` 字段来猜测仓库名（在使用前会向用户确认）。
78
+ 1. The `--repo` option passed on the command line.
79
+ 1. The `repo` field in the Markdown file's [metadata](https://github.com/cssmagic/kup/issues/1).
80
+ 1. The `kup.repo` field in the current project's `package.json`. Kup starts from the Markdown file's directory and searches upward for a `package.json` file.
81
+ 1. If `kup.repo` is not present in `package.json`, Kup will try to infer the repository name from the `repository` field and ask for confirmation before using it.
82
+ 1. If that still fails, Kup will continue searching for `.git/config` in the current or parent directories, then try to infer the repository name from the `url` field of `remote "origin"` and ask for confirmation before using it.
81
83
 
82
- 如果整个项目的同步目标都是同一个仓库，则建议采用 `kup.repo` 字段统一指定 `repo` 参数。
84
+ If the entire project syncs to the same repository, it is usually best to configure `kup.repo` in `package.json`.
83
85
 
84
- ### 如何更方便地指定 `id` 参数？
86
+ ### How can I specify the `id` option more conveniently?
85
87
 
86
- 有以下方式可以指定 `id` 参数，优先级递减：
88
+ Kup can determine the `id` option in the following order of priority:
87
89
 
88
- 1. 调用命令行时指定的 `--id` 参数。
89
- 1. Markdown 文件内的元数据的 `id` 字段。
90
+ 1. The `--id` option passed on the command line.
91
+ 1. The `id` field in the Markdown file's metadata.
90
92
 
91
- 当一个文件发布成功后，建议立即把 id 写入它的元数据。
93
+ After a file is successfully published as an issue, Kup immediately writes the `id` back into its metadata.
92
94
 
93
- ### Issue 的标题是怎么确定的？
95
+ ### How is the issue title determined?
94
96
 
95
- Kup 通过以下线索来确定 issue 的标题，优先级递减：
97
+ Kup determines the issue title using the following hints, in descending priority:
96
98
 
97
- 1. Markdown 文件内的元数据的 `title` 字段。
98
- 1. Markdown 正文的第一个标记如果是一级标题（`# Title` 格式），则取它的内容（在这种情况下，这个一级标题在同步时会从内容中排除）。
99
+ 1. The `title` field in the Markdown file's metadata.
100
+ 1. If the first Markdown block is an H1 heading (in `# Title` form), Kup uses its text as the title. In this case, that H1 heading is excluded from the synced content.
99
101
 
100
- 如果通过以上方式无法确定 issue 标题，Kup 会怎么处理？
102
+ What happens if Kup still cannot determine the issue title?
101
103
 
102
- * 如果是在发布新 issue，则 Kup 会自己生成一个标题。
103
- * 如果是在更新已有 issue，则 Kup 会忽略标题（也就是说，不会修改已有标题）。
104
+ * When publishing a new issue, Kup generates a title automatically.
105
+ * When updating an existing issue, Kup ignores the title, which means the existing title will not be changed.
104
106
 
105
- ### 如何为 issue 指定 label？
107
+ ### How do I assign labels to an issue?
106
108
 
107
- 不论是在写博客，还是在发表 issue，你常常都会有打标签的需求。于是 Kup 也实现了这个功能。
109
+ Whether you are blogging or publishing regular issues, labels are often useful, so Kup supports them as well.
108
110
 
109
- 你需要在 Markdown 文件的元数据中添加 `tags` 字段，指定一个或多个 label。这些 label 不需要事先在 GitHub 仓库里创建好——如果你指定了不存在的 label，会在发布 issue 时自动创建。
111
+ Add a `tags` field to the Markdown file's metadata and specify one or more labels. These labels do not need to exist in the GitHub repository beforehand. If a label does not already exist, it will be created automatically when the issue is published.
110
112
 
111
- 如果元数据中没有 `tags` 字段，Kup 会怎么处理？
113
+ What happens if there is no `tags` field in the metadata?
112
114
 
113
- * 如果是在发布新 issue，则 Kup 不会为 issue 设置任何 label。
114
- * 如果是在更新已有 issue 时，Kup 会忽略标签（也就是说，不会修改已有标签）。
115
+ * When publishing a new issue, Kup will not assign any labels.
116
+ * When updating an existing issue, Kup ignores labels, which means the existing labels will not be changed.
115
117
 
116
- 在更新已有 issue 时，如果元数据指定的标签与 issue 现有标签不一致，则前者会完全替代后者。
118
+ When updating an existing issue, if the labels specified in the metadata differ from the issue's current labels, the new set completely replaces the old one.
117
119
 
118
- ## 文档
120
+ ## Documentation
119
121
 
120
- * [Markdown 文件内的元数据示例](https://github.com/cssmagic/kup/issues/1)
121
- * [如何为 Kup 生成合适的 GitHub token](https://github.com/cssmagic/kup/issues/17)
122
+ * [Metadata examples for Markdown files](https://github.com/cssmagic/kup/issues/1)
123
+ * [How to generate an appropriate GitHub token for Kup](https://github.com/cssmagic/kup/issues/17)
122
124
 
123
125
 
124
- ## 其它
126
+ ## Other
125
127
 
126
- ### 开发计划
128
+ ### Roadmap
127
129
 
128
- 请参考 [本项目的 issue](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)。欢迎提出你的需求，或参与 RFC 讨论。
130
+ * See [the issue list for this project](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) for current plans.
131
+ * Feature requests and RFC discussions are welcome.
129
132
 
130
- ### 关于名字
133
+ ### About the Name
131
134
 
132
- * Kup 取自 “皮卡” 的英文词 pickup，喻意是 “轻便地运载”。
133
- * Kup 是变形金刚人物 “杯子” 的英文名。
135
+ * Kup comes from the English word "pickup", suggesting lightweight transport.
136
+ * Kup is also a character in *Transformers*.
134
137
 
135
- ### 关于 Logo
138
+ ### About the Logo
136
139
 
137
- * 作者 [Fasil](https://freeicons.io/profile/722)，由 [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893) 免费提供。
140
+ * The logo was created by [Fasil](https://freeicons.io/profile/722) and provided for free via [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893).
138
141
 
139
142
  ***
140
143
 
@@ -142,6 +145,6 @@ Kup 通过以下线索来确定 issue 的标题，优先级递减：
142
145
 
143
146
  > Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.
144
147
  >
145
- > 任何贡献到本项目的代码，均视为授权本项目作者及其名下公司用于商业用途、并按本项目协议分发。
148
+ > 任何贡献到本项目的代码，均视为授权本项目作者及其关联公司用于商业用途，并可按本项目协议进行分发。
146
149
 
147
150
  MIT
package/README.zh.md ADDED
@@ -0,0 +1,150 @@
1
+ [English](README.md) | 中文
2
+
3
+ # Kup
4
+
5
+ <img src="https://user-images.githubusercontent.com/1231359/171321963-e8e73bdf-f9c8-435b-9707-318e92f1805a.png" width="150" height="80" align="right" alt="Kup logo">
6
+
7
+ > A CLI tool to sync local Markdown files to GitHub issues.
8
+ >
9
+ > 这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。
10
+
11
+ ## 谁需要它
12
+
13
+ * 利用 GitHub issue 写博客的作者们，可以方便地在本地编辑原稿，并随时发布新博文或更新已有博文。
14
+ * 通过 GitHub issue 发布文档的开源软件作者们，可以把代码仓库中的文档更新到指定 issue。
15
+ * 其它需要频繁更新 GitHub issue 的人。
16
+
17
+
18
+ ## 安装
19
+
20
+ 需要全局安装，以便随时在命令行调用：
21
+
22
+ ```sh
23
+ npm install -g kup-cli
24
+ ```
25
+
26
+ （当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）
27
+
28
+
29
+ ## 使用方法
30
+
31
+ ### 发布新 issue
32
+
33
+ ```sh
34
+ kup ./path/to/file.md --repo foo/bar
35
+ ```
36
+
37
+ Kup 会把 `file.md` 文件的内容发布为 `foo/bar` 仓库的一个新 issue，发布成功后会告知新 issue 的编号。
38
+
39
+ ### 更新已有 issue
40
+
41
+ ```sh
42
+ kup ./path/to/file.md --repo foo/bar --id 123
43
+ ```
44
+
45
+ Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123` 的 issue。
46
+
47
+ ### 准备工作
48
+
49
+ 操作 GitHub issue 是需要权限认证的，因此你需要向 Kup 提供 GitHub token，以便 Kup 调用 GitHub API。
50
+
51
+ 1. 在 GitHub 的 “[Personal access tokens](https://github.com/settings/tokens)” 页面生成一个新 token，权限范围需要选中 “repo”。（详细说明参见 [这篇文档](https://github.com/cssmagic/kup/issues/17)。）
52
+
53
+ 2. 把获取到的 token 写入环境变量：
54
+
55
+ ```sh
56
+ export GITHUB_TOKEN=ghp_**********
57
+ ```
58
+
59
+ 如果 Kup 未能从环境变量获取 token，会在命令行向你询问。
60
+
61
+
62
+ ## 命令行参数
63
+
64
+ 参数 | 短名 | 值类型 | 含义 | 备注
65
+ ---|---|---|---|---
66
+ `--repo` | `-r` | 字符串 | 指定 GitHub 仓库
67
+ `--id` | `-i` | 整数 | 指定 issue 的编号 | <ul><li>指定编号表示更新已有 issue<li>未指定编号则表示发布新 issue</ul>
68
+ `--version` | `-v` | - | 显示版本号
69
+ `--help` | `-h` | - | 显示帮助信息
70
+
71
+
72
+ ## 进阶
73
+
74
+ ### 如何更方便地指定 `repo` 参数？
75
+
76
+ 有以下方式可以指定 `repo` 参数，优先级递减：
77
+
78
+ 1. 调用命令行时指定的 `--repo` 参数。
79
+ 1. Markdown 文件内的 [元数据](https://github.com/cssmagic/kup/issues/1) 的 `repo` 字段。
80
+ 1. 当前项目的 `package.json` 文件内的 `kup.repo` 字段。Kup 会以 Markdown 文件所在目录为起点逐级向上寻找 `package.json` 文件。
81
+ 1. 如果 `package.json` 文件内没有 `kup.repo` 字段，则 Kup 会尝试根据 `repository` 字段来猜测仓库名（在使用前会向用户确认）。
82
+ 1. 如果以上方式都没有成功，则 Kup 会继续查找同级或上级目录中的 `.git/config` 文件，并尝试根据其中 `remote "origin"` 的 `url` 字段来猜测仓库名（在使用前会向用户确认）。
83
+
84
+ 如果整个项目的同步目标都是同一个仓库，通常建议在 `package.json` 里统一配置 `kup.repo`。
85
+
86
+ ### 如何更方便地指定 `id` 参数？
87
+
88
+ 有以下方式可以指定 `id` 参数，优先级递减：
89
+
90
+ 1. 调用命令行时指定的 `--id` 参数。
91
+ 1. Markdown 文件内的元数据的 `id` 字段。
92
+
93
+ 当一个文件成功发布为 issue 后，Kup 会立即把 `id` 写入它的元数据中。
94
+
95
+ ### Issue 的标题是如何确定的？
96
+
97
+ Kup 会通过以下线索来确定 issue 的标题，优先级递减：
98
+
99
+ 1. Markdown 文件内的元数据的 `title` 字段。
100
+ 1. Markdown 正文的第一个标记如果是一级标题（`# Title` 格式），则取它的内容（在这种情况下，这个一级标题在同步时会从内容中排除）。
101
+
102
+ 如果通过以上方式无法确定 issue 标题，Kup 会怎么处理？
103
+
104
+ * 如果是在发布新 issue，则 Kup 会自己生成一个标题。
105
+ * 如果是在更新已有 issue，则 Kup 会忽略标题（也就是说，不会修改已有标题）。
106
+
107
+ ### 如何为 issue 指定 label？
108
+
109
+ 不论是在写博客，还是在发表 issue，你常常都会有打标签的需求。因此 Kup 也实现了这个功能。
110
+
111
+ 你需要在 Markdown 文件的元数据中添加 `tags` 字段，指定一个或多个 label。这些 label 不需要事先在 GitHub 仓库里创建好——如果你指定了不存在的 label，会在发布 issue 时自动创建。
112
+
113
+ 如果元数据中没有 `tags` 字段，Kup 会怎么处理？
114
+
115
+ * 如果是在发布新 issue，则 Kup 不会为 issue 设置任何 label。
116
+ * 如果是在更新已有 issue 时，Kup 会忽略标签（也就是说，不会修改已有标签）。
117
+
118
+ 在更新已有 issue 时，如果元数据指定的标签与 issue 现有标签不一致，则前者会完全替代后者。
119
+
120
+ ## 文档
121
+
122
+ * [Markdown 文件内的元数据示例](https://github.com/cssmagic/kup/issues/1)
123
+ * [如何为 Kup 生成合适的 GitHub token](https://github.com/cssmagic/kup/issues/17)
124
+
125
+
126
+ ## 其它
127
+
128
+ ### 开发计划
129
+
130
+ * 请参考 [本项目的 issue 列表](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) 来了解当前规划。
131
+ * 欢迎提交需求，或参与 RFC 讨论。
132
+
133
+ ### 关于名字
134
+
135
+ * Kup 取自 “皮卡” 的英文词 pickup，喻意是 “轻便地运载”。
136
+ * Kup 是变形金刚人物 “杯子” 的英文名。
137
+
138
+ ### 关于 Logo
139
+
140
+ * Logo 由 [Fasil](https://freeicons.io/profile/722) 创作，并通过 [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893) 免费提供。
141
+
142
+ ***
143
+
144
+ ## License
145
+
146
+ > Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.
147
+ >
148
+ > 任何贡献到本项目的代码，均视为授权本项目作者及其关联公司用于商业用途，并可按本项目协议进行分发。
149
+
150
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kup-cli",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "A CLI tool to sync local Markdown files to GitHub issues.",
5
5
  "type": "module",
6
6
  "bin": {