Add CONTRIBUTING.md #15

S1ngS1ng · 2018-07-23T06:42:36Z

Add guide of git

TODO

Style guide

huluoyang · 2018-07-23T14:53:48Z

CONTRIBUTING.md

+- branch：分支
+- commit：提交记录
+- merge：指 PR 合并到代码仓库的操作
+- conflicts：合并冲突


conflicts 虽然是合并产生的冲突，但这里翻译成冲突要好些。

@huluoyang 考虑了下，这里我觉得还是用“合并冲突”好些。
因为这里描述的内容都是和 git 相关的，上面的也是。
conflicts，在 git 中只以 merge conflicts 一种形式出现，哪怕 cherry-pick 产生的也叫 merge conflicts

这样吧：

huluoyang · 2018-07-23T14:55:57Z

CONTRIBUTING.md

+- conflicts：合并冲突
+
+## 开始之前
+1. 首先，fork 一下 [challenges](https://github.com/FreeCodeCampChina/challenges/pulls) repo


仓库地址应该是：https://github.com/FreeCodeCampChina/challenges.git

@huluoyang 好。这个我回家改

huluoyang · 2018-07-23T14:58:40Z

CONTRIBUTING.md

+```
+4. 根据你在翻译的项目名称或者你正在做的事情，新建分支。注意，`your_branch_name` 是你的分支名，如 `translate-basic-html-and-html5`：
+```bash
+git checkout -b your_branch_name


git branch your_branch_name 新建分支
git checkout you_branch_name 切换分支
建议分两步，不要用简写的方式。

@huluoyang 所以先 git branch 然后再 checkout 会有什么潜在的风险？因为如果在 git branch 那一步出了问题，哪怕是简写也不会有任何 side effect，本地不会有任何变化。

而且，习惯上，在新建 branch 之后就会切换过去。一个合理的猜想是在新建 branch 之后会设置它的 tracking branch（尽管一般这个步骤都是发生在切换之后），然而这个也可以通过

git checkout -b your_branch_name some_remote/some_branch

来实现。因此，我看不到分两步的必要。
在新建 branch 之后，你除了切换过去，还做过什么操作？我能想到的就是设置 tracking。

至于该不该用简写，比如，我们都习惯了 git pull，然而它本身就是 git fetch + git merge。为何我们不分开呢？

有些命令是我觉得需要分开的，比如：

git add . git commit -m "xxx"

有时候可以合并成 git commit -am "xxx"。但这样推荐显然是不必要的。

关于是否应该简写，确实在不同的场景下应该有不同的做法。
为什么大家习惯 git pull，是因为这是一个单独的命令，从名字上就很好理解。

git add . git commit -m "xxx"

为什么要建议分开写呢？因为这两步本来就代表不同的操作，用 git commit -am "xxx" 并没有简化用户思维，依然需要弄清参数 a 的意思。

git checkout -b your_branch_name
同理，这个操作对新手依然不友好，需要记忆参数 b 的意思。分两步写，新手一看就懂。

个人总结：如果有单独的命令来简化原来的多步操作，推荐用单独的命令。反之，还是用多步操作。

使用前提：以上只针对新手，高手例外。

huluoyang · 2018-07-23T15:06:19Z

CONTRIBUTING.md

+```bash
+git commit -m "My commit message"
+
+# 或者你也可以打开你喜欢的编辑器（需要配置），在里面编写 commit message


建议这部分去掉，实际上在编辑器里写 commit 的情形很少，commit 信息尽量一行写完。

@huluoyang 之所以放在这里，一方面是告知大家如果这么做会发生什么，另一方面，我一直都是在 vim 里写 commit message 的。

至于原因，首先，你说的一行写完，个人觉得指的应该是 “message header”（推荐是 50 字以内），但这与 commit message 里有 messsage body 并不冲突。message header 与 message body 通过第一个空行区分。所以我会选择在 vim 里输入。

参考：https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project 中 Commit Guidelines 部分

其次，多行的 commit message 不是必须的，但我们在需要的时候可以采用，特别是 squash and merge 的时候。

以及，它丝毫不会影响 commit history 在 github 页面或命令行的外观：

截图来自 freeCodeCamp/freeCodeCamp。注意到有个 commit 有三个点。点开之后：

这才是 message body

命令行里也很好办。git log 会输出 header 及 body，但 git log --oneline 就不会了。我设置了一个 alias，对应的是 git log --oneline --decorate --graph，看起来会很直观

OK，这部分，我同意你的意见。

你这个 alias，很有意思啊，确实能大幅提高 git 的操作效率，Mark it。

huluoyang · 2018-07-23T15:07:38Z

CONTRIBUTING.md

+9. 打开 github 页面，创建 PR
+
+## 同步远程更新至本地
+1. 关联上游 repo 至本地项目。注意，`upstream` 只是一个本地的 reference，你可以根据自己的习惯命名：


注意部分可去掉。如无必要，勿增实体。

@huluoyang 好的。这个可以改，因为按照这个顺序下来，用户本地应该只有 origin

huluoyang · 2018-07-23T18:37:49Z

CONTRIBUTING.md

+    ```
+    2. 使用 rebase 命令：
+    ```bash
+    git fetch upstream


git fetch 只获取，并不 merge，所以此处不合适。

@huluoyang 下一行就是 rebase 了

@S1ngS1ng rebase 并不会 merge 啊，所以用 fetch 肯定不合理。

@huluoyang rebase 当然不会 merge，因为 rebase 和 pull 本身就是两个不同的做法。
上面的意思是，两种选择，要么 git pull，要么先 git fetch upstream 再 git rebase upstream/translate。
对于 rebase，必须要先 fetch

huluoyang · 2018-07-23T18:39:07Z

CONTRIBUTING.md

+    ```
+    3. 使用 pull 命令与 rebase flag（推荐）：
+    ```bash
+    git pull --rebase upstream translate


一条命令包含太多信息，对新手不友好，高手可以这样操作。

@huluoyang 我倒不觉的这是个问题。复制粘贴，设置命令行 alias 总是可以的，不需要每次都手打啊。以及只比 git pull upstream translate 多了个 --rebase。

以及，我认为 --rebase 是十分必要的。多次 pull，最后麻烦的其实是我们自己

huluoyang · 2018-07-23T18:42:40Z

CONTRIBUTING.md

+    ```
+
+## 注意
+1. `pull` 或 `rebase` 之后，如果有 conflicts，可以先使用 `git status` 查看存在 conflicts 的文件。修改成需要的版本后：


此处可全部替换成：
git pull upstream translate 命令执行后，命令行会出现一个 vim 的编辑器界面。
在此界面中，输入:wq，表示保存 merge 信息。

pull --rebase 我记得是不会的，它应该和 rebase 是一样的，所以后面说了，用 rebase --continue。容我回去确认下。

此处能够尽量减少操作是最好的，如果 --continue 能够解决就最好了。
目前我们的翻译流程依然不够简洁，中间也缺失关键步骤，这部分目前是靠个人的经验来弥补的。

@huluoyang 事实证明，可以的

huluoyang · 2018-07-23T18:45:13Z

CONTRIBUTING.md

+```bash
+git push origin your_branch_name
+```
+3. 如果出现错误提示（多出现于 `rebase` 和 `pull` 命令），请先使用 `git status` 命令检查本地是否有未解决完成的 conflicts


任何时候出现错误，不要慌，请先使用 git status 命令检查当前所在的分支、当前目录是否纯净、本地是否有未解决完成的 conflicts。

huluoyang · 2018-07-23T18:46:17Z

CONTRIBUTING.md

+4. 如果你已经用当前的 branch 开了 PR，那么更新这个 branch 至远程的同时，你的 PR 也会自动更新
+
+## 一些原则
+1. 建议使用 [git workflow](https://guides.github.com/introduction/flow/) 来进行分支的管理。这样我们可以提交 PR 之后继续在新的 branch 上进行后续的翻译。若需要更新当前的 PR，任何时候我们都可以切换回来


任何时候我们都可以切换回来 => 我们随时可以切换回来

- Pick pull --rebase among three options - Update guideline of resolving conflicts

S1ngS1ng · 2018-07-25T17:11:44Z

CONTRIBUTING.md

+    可以。建议使用本地的 translate 分支保持与 upstream 中的 translate 分支保持更新。这样做的好处是：
+    <ol>
+        <li>每次新建分支的时候，切换到本地的 translate 分支，然后 <code>git checkout -b my_new_branch</code> 就好了</li>
+        <li>如果 upstream 的 translate branch 有更新，你只需要在切换到 translate 分支之后，<code>git pull --rebase upstream/translate</code> 即可完成对本地 translate 分支的更新。再创建新的分支，就是基于 upstream 里最新的代码了，这样可以减少 conflicts 出现的可能</li>


Wrong path, pending update @Robin-zero

S1ngS1ng · 2018-07-25T17:11:50Z

CONTRIBUTING.md

+<details>
+    <summary>我在一个分支上 commit 了我的代码，这时候 upstream 更新了，我该怎么做？</summary>
+    <pre><code>
+    git pull --rebase upstream/translate


S1ngS1ng · 2018-07-25T17:11:56Z

CONTRIBUTING.md

+    <summary>命令好长，我不想记</summary>
+    <code>alias</code> 了解一下。在命令行里执行：
+    <pre><code>
+    git config --global alias.gx 'pull --rebase upstream/translate'


S1ngS1ng · 2018-07-25T17:13:21Z

CONTRIBUTING.md

+5. 在本地进行代码或文件修改
+6. 修改完成后，先添加要提交的文件：
+```bash
+git add .        # 添加全部有改动的文件


Needs clarification for . and -A => FAQ

S1ngS1ng · 2018-07-25T17:14:10Z

CONTRIBUTING.md

+1. 建议使用 [git workflow](https://guides.github.com/introduction/flow/) 来进行分支的管理。这样我们可以提交 PR 之后继续在新的 branch 上进行后续的翻译。若需要更新当前的 PR，我们随时可以切换回来
+2. 不建议同时开两个相同类型（比如翻译）的 PR，请等待之前的 merge 之后再开新的 PR
+3. 如果你的 PR 已经被 review 过，请不要再添加新的翻译内容，根据 comment 修改好当前的 PR 即可。后续的翻译你可以等当前翻译 merge 后再开始做，或者在另一个本地的 branch 进行后续的翻译
+4. 更新（创建）PR 时，请更新 labels，方便管理


Pending removal

… add . vs git add -A

更新了下排版

更改符号的使用

continue fix some type error

continue

huluoyang · 2018-07-26T09:59:25Z

我直接修改了下排版和符号的使用。

* Add CONTRIBUTING.md, add guide of git * address review comments - Pick pull --rebase among three options - Update guideline of resolving conflicts * Add git FAQ. Remove labels def as for not needed * Fix style issue, using HTML tags * Update Details w/ GFM, fix wrong command * Update FAQ with guide of resolving conflicts and clarification of git add . vs git add -A * Update CONTRIBUTING.md 更新了下排版 * Update CONTRIBUTING.md 更改符号的使用 * Update CONTRIBUTING.md continue fix some type error

S1ngS1ng added the ready for review Use when a translation (?) PR is ready for review label Jul 23, 2018

S1ngS1ng requested a review from huluoyang July 23, 2018 06:42

huluoyang suggested changes Jul 23, 2018

View reviewed changes

Add CONTRIBUTING.md, add guide of git

6b5b787

S1ngS1ng force-pushed the contribution-guide branch from 56a2ead to 1fe51fa Compare July 24, 2018 06:12

address review comments

b828a03

- Pick pull --rebase among three options - Update guideline of resolving conflicts

S1ngS1ng force-pushed the contribution-guide branch from 1fe51fa to b828a03 Compare July 24, 2018 06:13

S1ngS1ng added the comments addressed Use when a translation (?) PR has addressed all comments label Jul 24, 2018

Add git FAQ. Remove labels def as for not needed

f620003

S1ngS1ng force-pushed the contribution-guide branch from 94ff6e7 to a99db5a Compare July 25, 2018 07:37

Fix style issue, using HTML tags

3dc6cf8

S1ngS1ng force-pushed the contribution-guide branch from a99db5a to 3dc6cf8 Compare July 25, 2018 07:39

S1ngS1ng commented Jul 25, 2018

View reviewed changes

S1ngS1ng added need update Use when a translation (?) PR has been reviewed and needs to address comments and removed comments addressed Use when a translation (?) PR has addressed all comments labels Jul 26, 2018

S1ngS1ng added 2 commits July 25, 2018 20:40

Update Details w/ GFM, fix wrong command

a870450

Update FAQ with guide of resolving conflicts and clarification of git…

bd184b7

… add . vs git add -A

S1ngS1ng force-pushed the contribution-guide branch from 58756ed to bd184b7 Compare July 26, 2018 04:16

huluoyang added 5 commits July 26, 2018 17:28

Update CONTRIBUTING.md

2f0abbf

更新了下排版

Update CONTRIBUTING.md

5d0b6ac

更改符号的使用

Update CONTRIBUTING.md

eeac2bd

continue fix some type error

Update CONTRIBUTING.md

03a33a4

continue

Update CONTRIBUTING.md

2862c12

huluoyang merged commit 9a57137 into FreeCodeCampChina:translate Jul 26, 2018

Add CONTRIBUTING.md #15

Add CONTRIBUTING.md #15

Uh oh!

Conversation

S1ngS1ng commented Jul 23, 2018

TODO

Uh oh!

Choose a reason for hiding this comment

Uh oh!

S1ngS1ng Jul 24, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

S1ngS1ng Jul 23, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

S1ngS1ng Jul 23, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huluoyang Jul 24, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

S1ngS1ng Jul 24, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

S1ngS1ng Jul 23, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

S1ngS1ng Jul 25, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huluoyang commented Jul 26, 2018

S1ngS1ng Jul 24, 2018 •

edited

Loading

S1ngS1ng Jul 23, 2018 •

edited

Loading

S1ngS1ng Jul 23, 2018 •

edited

Loading

huluoyang Jul 24, 2018 •

edited

Loading

S1ngS1ng Jul 24, 2018 •

edited

Loading

S1ngS1ng Jul 23, 2018 •

edited

Loading

S1ngS1ng Jul 25, 2018 •

edited

Loading