(图片来源:Chris Lawton @ Unsplash)
我每个秋天都爱Hacktoberfest - 我试图有意识地为OSS世界做出了一些贡献的时代,这给了我们所有的东西。
今年,我正在考虑如何与过去几年相比对Hacktoberfest的处理方式有所不同。以下是我的经验;也许它也会为您解锁!
我今年的hacktoberfest捐款的个人标准
我希望我的hacktoberfest贡献为:
- 不是一个巨大的升降机。我现在有限的时间来贡献。
- 不是开车或微小的变化。只是感觉我可以做的比目标贡献要好一些(每当我看到它们时,我都会定期做。)
- 死记硬背,因为在停机时间里,我发现小的可重复任务是放松的好方法。
- 我可以写的东西,以便其他人可以与 一起运行并运行
- 可以适用于大小项目,以及流行和晦涩的项目。
•和背景思想
我一直在考虑如何从OSS中的更多相互援助以及需求市场中受益。如果我们可以系统化某些类型的改进,我们可以帮助他人教别人如何进行这些改进,我们可以帮助将受益于这些改进的项目。对我来说,听起来像是真正的双赢,我很乐意看到一个枢纽弹起以提供这种相互帮助。 (并且可以自己创建一个。)
今年的选择:拼写检查!
看起来很小,但是许多开发项目都有文档。其中许多文档都有拼写错误。以我的经验,许多维护者欢迎偶尔进行拼写校正,并可能会欣赏防止错误的错误。
如何为OSS文档添加拼写检查
我做了以下操作以实现它:
添加github操作工作流和空的CSPELL配置文件
首先,我在.github/workflows/spellcheck.yml
或类似的情况
name: Documentation Checks
on:
push:
branches:
- master #or main if that's what the project is using
paths:
# This ensures the check will only be run when something changes in the docs content
- "content/**/*" # or whatever the path to the markdown / docs files happens to be
pull_request:
branches:
- master
paths:
- "content/**/*"
jobs:
spellcheck:
name: "Docs: Spellcheck"
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
name: Check out the code
- uses: actions/setup-node@v1
name: Setup node
with:
node-version: "16"
- run: npm install -g cspell
name: Install cSpell
- run: cspell --config ./cSpell.json "content/**/*.md" --no-progress # Update for path to the markdown files
name: Run cSpell
,然后在项目根或其文档的根部中一个模板cSpell.json
文件:
{
"version": "0.2",
"language": "en",
"words": [
],
"ignoreWords": [
],
"patterns": [
{
"name": "Markdown links",
"pattern": "\\((.*)\\)",
"description": ""
},
{
"name": "Markdown code blocks",
"pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx",
"description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions"
},
{
"name": "Inline code blocks",
"pattern": "\\`([^\\`\\r\\n]+?)\\`",
"description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex"
},
{
"name": "Link contents",
"pattern": "\\<a(.*)\\>",
"description": ""
},
{
"name": "Snippet references",
"pattern": "-- snippet:(.*)",
"description": ""
},
{
"name": "Snippet references 2",
"pattern": "\\<\\[sample:(.*)",
"description": "another kind of snippet reference"
},
{
"name": "Multi-line code blocks",
"pattern": "/^\\s*```
[\\s\\S]*?^\\s*
```/gm"
},
{
"name": "HTML Tags",
"pattern": "<[^>]*>",
"description": "Reference: https://stackoverflow.com/questions/11229831/regular-expression-to-remove-html-tags-from-a-string"
}
],
"ignoreRegExpList": [
"Markdown links",
"Markdown code blocks",
"Inline code blocks",
"Link contents",
"Snippet references",
"Snippet references 2",
"Multi-line code blocks",
"HTML Tags"
],
"ignorePaths": []
}
对此快速分解:
-
words
表示我们希望拼写检查 的有效词
-
ignoreWords
表示我们不想显示为拼写错误的单词,但我们也不希望工具作为有效的替代品建议。 -
patterns
定义了我们希望能够忽略的正则方式,然后将其放在ignoreRegExpList
中。- â·见¸实际上是我在今年创建拉的请求期间学到的!在此之前,我正在使用评论,因为Json确实应该拥有它们,这很混乱。
-
ignorePaths
用于排除CSPELL检查中的文件或地球。
创建一个正在进行的工作请求
我相信,尽早创建拉力请求,以便我可以用它们作为我以拉拉请求的评论形式留下的小提交和思想日记。这具有一些功能:
- 如果某人对我的贡献不感兴趣,他们可以告诉我并为我们节省很多时间。
- 如果有人有疑问,他们可以在此过程中问他们。
- 他们可以看到单独的承诺以及我的推理背后是什么。
运行CSPELL
接下来,i:
- 安装节点16(我使用nvm,所以是
nvm install 16.x
,然后是nvm use [version I installed]
)。 - 全球安装CSPELL(
npm i -g cSpell
) - 在本地运行与我设置GitHub动作的同一cspell命令,例如
cspell --config ./cSpell.json "content/**/*.md" --no-progress
- 当您只是在寻找错误时,
--no-progress
会减少噪音,因为它不会输出每个文件名。
- 当您只是在寻找错误时,
有趣的部分:解决发现!
查看Cspell结果。如果您使用VS代码,则可以单击查找,它将带您在编辑器中。
cspell发现通常分为几类:
- 实际拼写错误。这些可以作为一次性修复,也可以通过在常见拼写的情况下通过查找和替换。
- 标准化,例如
colour
在英国拼写与color
中的美国英语中。在这些情况下,我通常会注意到它们,并询问作者是否希望我还原它们。我在使用美国英语的默认方法中使用cspell的默认值。 - 可能不是作为单词而是其他术语的术语,例如一个变量名称。我通过尝试根据其DOC系统的偏好进行格式化来解决这一问题,这通常是在该术语围绕the键。
- 可能被排除的整个文件,例如大型发行说明文件,其中从问题中复制文本,并可能拼写错误。或主要包含html的降价页面。
- 代码片段突出显示。当我遇到这些时,我会使用适当的降压添加代码围栏。
- CSPELL应该没有拿起一些东西,而是因为缺少正则忽略模式。我尝试在发生时修复它并添加模式。
- 我们想添加到字典中。这些可能是作者使用的特定于领域的词,或者其他常用词在Cspell的词典中不恰好。 CSPELL的S VS代码集成使您能够击中
CTRL + .
的可爱功能,以提出一个拼写检查菜单,您可以使用该菜单将单词添加到您创建的cSpell.json
文件中。 - 我们想忽略的话;它们不正确,但我们不希望他们被建议。通常,名称属于此类别,尽管我经常将作者的名字放入我们要添加类别的单词中。
- âKisscell的vs代码集成没有办法在忽略列表中添加单词,因此我通常在
cSpell.json
之后的words
列表上进行通过,然后将它们分开。<<<<。 /li>
- âKisscell的vs代码集成没有办法在忽略列表中添加单词,因此我通常在
重要的最后一部分:适应反馈
拼写和单词选择是个人的事情。我认为,只要维护者有意识和一致地做出选择,那就不会是错误的。任何咒语检查系统都应适应它。我对维护者偏好的任何推杆都很少。这不是要纠正某人;这是有帮助的。
- 我对我在github上的PR进行自我审查
- 我提请注意维护者可能想称重的事情
- 我明确要求反馈并适应它。
我在哪里贡献了这些更改?
您可以看到我一路上收到的一些问题和反馈,以及那些没有发现有用的存储库。
下一部分取决于您!
寻找可以完成#hacktoberest挑战的东西,同时对此感到满意?想在大型项目的文档中有所作为吗?
尝试这种方法,让我知道您的工作方式!我也很乐意让你不吃。将我标记为任何公关,您在此遇到问题。向我们展示您在评论中的进度!