diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5ebb850f..87a29f57 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,4 +14,4 @@ jobs: - name: Install packages run: sudo gem install mdl - name: Lint markdown files - run: mdl *.md -r ~MD029,~MD036,~MD024 + run: mdl *.md -r ~MD009,~MD029,~MD036,~MD024 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..5fc4af00 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# CONTRIBUTING Guide + +## 为什么会有这个项目 (Motivation) + +Add some motivation here. @Anduin + +Recolic的个人观点: 菜谱的目的是复现一道菜。在做菜的过程中,菜会受厨师的经验、主观判断、生活经历而改变。 +但是为了达到`复现一道菜`的目的,菜谱必须是客观的,也就意味着菜谱本身不应受厨师的经验、主观判断而改变。 +菜的创作者(厨师)、菜的记录者(菜谱)、菜的生产者(饥饿的程序员、炒菜机器人)应当是三个不同的角色。如果生产者偶尔心情愉悦,可以兼职为创作者。但记录者是为生产者服务的。 + +## 新内容注意事项 + +此仓库中的菜谱需要满足以下规范,不符合规范的菜谱将不会被合并到代码库中。 + +1. 每一道菜谱至少应包含`原材料与工具`, `计算`, `操作`三部分内容。 + +`原材料与工具`应列出本菜品需要的除`假想已准备好的物品`外的所有原材料与厨具。 +`计算`应定量列出本菜品所需的原材料的量。(无论与人数是否相关) +`操作`应说明菜品的制作步骤。 + +2. 菜品的制作步骤应当明确(无歧义,non-ambiguous),并尽可能准确(accurate)。有歧义(ambiguous)的描述是不可接受的,而不准确(inaccurate)或不精确(imprecise)的描述是可以接受的。 + +> 不准确的菜谱会导致菜品口味有少许偏差,不明确的菜谱会导致做菜人的心态有明显不安。 + +举例:有歧义的描述 + +``` +# 解释:此处对于盐量的描述是有歧义的。 +# 因为对于某个数量的盐,用户无法得出确定的客观结论:此数量是否属于"少量"。 +加入少量盐 + +加入几滴耗油 +将锅加热至八分热 +撒上少许葱花 +煮至鸡肉断生 +``` + +举例:无歧义的描述 + +``` +# 解释:此处对于锅的温度的描述是不准确的(可能是200摄氏度左右的任何温度),但这个描述是无歧义的。 +# 因为对于锅的某个状态,用户可以进行水滴测试,并得出确定的客观结论:此状态要么符合要求,要么不符合要求。 +加热锅,直至"滴入几滴水时,水珠能够在锅上迅速滚动而不吸附" +加热锅,直至观察到莱顿弗罗斯特现象 + +加入5ml酱油 +等到水沸腾后 +继续煮,直到汤汁剩下二分之一 +煎至表面呈金黄色 +继续翻炒两分钟 + +# 食材所可能粘附的蛋液的量是确定的 +裹上蛋液 + +# 在'计算'中已提及将用到葱花的量 +撒上葱花 +``` + +考虑到现实因素,对于某些在家庭厨房中确实难以明确描述的因素,作为特例,允许使用以下词汇。 + +``` +# 在描述燃气灶火焰强度时 +文火, 小火, 中火, 大火 等 +# 在描述颜色时 +金黄色 等 +``` + +3. 菜品的制作步骤应当完整(complete)。 + diff --git a/README.md b/README.md index 9e0c9a72..c09a8951 100644 --- a/README.md +++ b/README.md @@ -98,14 +98,5 @@ ## 如何贡献 -直接修改这部分做菜指南并提交 Pull request 即可。 +直接进行修改并提交 Pull request 即可。为了保证您的PR被及时合并,建议阅读[贡献指南](./CONTRIBUTING.md)。 -补充菜谱时,针对一道菜,必须给出其`必需原材料`,`原材料用量计算公式`。 - -必须清晰准确的描述过程。在描述过程时不得加入上文或原材料中未提及的食材。凡是需要等待的步骤必须给出`等待时间计算公式`或`结束一个步骤的判断标准`。 - -使用 markdown 描述这道菜的`必需原材料`、`计算公式`、`操作步骤`、`附加内容`。如果有参考资料,请一并给出。 - -不允许使用不精准描述的词汇,例如:`适量`、`少量`、`中量`、`适当`。 - -不完整或不符合上述规范的菜谱将不会被允许合并到代码库中。