标签 Github 下的文章

Getting Started With GitHub

GitHub 是一个在线平台,旨在促进在一个共同项目上工作的个人之间的代码托管、版本控制和协作。通过该平台,无论何时何地,都可以对项目进行操作(托管和审查代码,管理项目和与世界各地的其他开发者共同开发软件)。GitHub 平台为开源项目和私人项目都提供了项目处理功能。

关于团队项目处理的功能包括:GitHub 流 Flow> 和 GitHub 页 Pages 。这些功能可以让需要定期部署的团队轻松处理工作流程。另一方面,GitHub 页提供了页面用于展示开源项目、展示简历、托管博客等。

GitHub 也为个人项目提供了必要的工具,使得个人项目可以轻松地处理。它也使得个人可以更轻松地与世界分享他们的项目。

注册 GitHub 并启动一个项目

在 GitHub 上启动新项目时,您必须先使用您的电子邮件地址创建一个帐户。

github homepage

然后,在验证邮箱的时候,用户将自动登录到他们的 GitHub 帐户。

1、 创建仓库

之后,我们会被带到一个用于创建 仓库 repository 的页面。​仓库存储着包括修订历史记录在内的所有项目文件。仓库可以是公开的或者是私有的。公开的仓库可以被任何人查看,但是,只有项目所有者授予权限的人才可以提交修改到这个仓库。另一方面,私有仓库提供了额外的控制,可以将项目设置为对谁可见。因此,公开仓库适用于开源软件项目,而私有仓库主要适用于私有或闭源项目。

  • 填写 “ 仓库名称 Repository Name ” 和 “ 简短描述 Short Description ”。
  • 选中 “ 以一个 README 文件初始化 Initialize this repository with a README ”。
  • 最后,点击底部的 “ 创建仓库 Create Repository ” 按钮。

create a github repository

2、 添加分支

在 GitHub 中, 分支 branch 是一种同时操作单个仓库的各种版本的方式。默认情况下,任何创建的单个仓库都会被分配一个名为 “MASTER” 的分支,它被认为是最后一个分支。在 GitHub 中,分支在被合并到 主干 master (最后的分支)之前,可以在对仓库进行实验和编辑中发挥作用。

为了使项目适合每一个人的需求,通常情况下,总是需要添加几个格外的分支来匹配不同的项目。在主分支上创建一个分支和复制主分支时的当前状态是一样的。

add a branch to github repository

创建分支与在不同版本中保存单个文件是类似的。它通过在特定仓库上执行的任务重命名来实现。

分支在保持错误修复和功能添加工作中同样被证明是有效。在进行必要的修改后,这些分支会被合并到主分支中。

在创建仓库后创建一个分支:

  • 在这个例子中,点击仓库名称 “Hello-World” 跳转到你的新仓库。
  • 点击顶部的 “Branch:Master” 按钮,会看到一个下拉菜单,菜单里有填写分支名称的空白字段。
  • 输入分支名称,在这个例子中我们输入 “readme-edits“。
  • 按下回车键或者点击蓝色的 “ 创建分支 create branch ” 框。

这样就成功创建了两个分支:master 和 readme-edits。

3、 修改项目文件并提交

此步骤提供了关于如何更改仓库并保存修改的指导。在 GitHub 上, 提交 commit 被定义为保存的修改的意思。每一次提交都与一个 提交信息 commit message 相关联,该提交信息包含了保存的修改的历史记录,以及为何进行这些更改。这使得其他贡献者可以很轻松地知道你做出的更改以及更改的原因。

要对仓库进行更改和提交更改,请执行以下步骤:

  • 点击仓库名称 “Hello-World”。
  • 点击右上角的铅笔图标查看和编辑文件。 commit changes to github repository
  • 在编辑器中,写一些东西来确定你可以进行更改。
  • 在 提交消息 commit message 字段中做简要的总结,以解释为什么以及如何进行更改。
  • 点击 提交更改 commit changes 按钮保存更改。

请注意,这些更改仅仅影响到 readme-edits 分支,而不影响主分支。

commit branch to master

4、 开启一个拉取请求

​拉取请求 pull request 是一个允许贡献者提出并请求某人审查和合并某些更改到他们的分支的功能。​拉取请求还显示了几个分支的差异(diffs)。更改、添加和删减通常以红色和绿色来表示。一旦提交完成就可以开启​拉取请求,即使代码还未完成。

开启一个​拉取请求:

  • 点击​ ​拉取请求 pull requests 选项卡。 github pull request
  • 点击 新建拉取请求 new pull requests 按钮。
  • 选择 readme-edits 分支与 master 分支进行比较。 compare commit changes github
  • 确定请求,并确定这是您要提交的内容。
  • 点击创建​拉取请求绿色按钮并输入一个标题。 open a pull request in github repository
  • 按下回车键。

用户可以通过尝试创建并保存拉取请求来证实这些操作。

5、 合并拉取请求

最后一步是将 readme-edits 分支和 master 分支合并到一起。如果 readme-edits 分支和 master 分支不会产生冲突,则会显示 merge pull request 合并拉取请求 的按钮。

merge the pull request github

当合并拉取时,有必要确保 评论 comment 和其他字段被正确填写。合并拉取:

  • 点击 merge pull request 合并拉取请求 的按钮。
  • 确认合并。
  • 按下紫色的删除分支按钮,删除 readme-edits 分支,因为它已经被包含在 master 分支中。(LCTT 译注:如果是合并他人提交的拉取请求,则无需也无法删除合并过来的他人的分支。)

本文提供了 GitHub 平台从注册到使用的基本操作,接下来由大家尽情探索吧。


via: http://www.linuxandubuntu.com/home/getting-started-with-github

作者:LinuxAndUbuntu 译者:firmianay 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

 title=

在未来的 12 到 24 个月内(也就是说,在 2018 年,或者是 2019 年),人们雇佣软件开发者的方式将会发生彻底的改变。

2004 至 2014 期间,我曾经就职于红帽,这是世界上最大的开源软件公司。还记得 2004 年七月的一天,我第一次来到这家公司,我的老板 Marty Messer 就跟我说,“所有你在这里所做的工作都会被开源,在未来,你将不需要任何的简历,因为所有的人都可以 Google 到你。”

供职于红帽的一个独特的好处是,在这种开源的工作期间,我们有机会建立自己的个人品牌和树立自己的声誉。我们可以通过邮件列表和 bug 追踪器与其它的软件工程师进行沟通,而且提交到 mercurial、subversion 和 CVS 仓库的源代码都会被开源,并且可以通过 google 找到。

(写本文时)马上就到 2017 年了,我们将生活在一个处处充满开源的世界。

以下两点会让你对这个新时代有一个真正意义上的了解:

  1. 微软在过去的一段很长的时间里都在坚持闭源,甚至是排斥开源。但是现在也从心底里开始拥抱开源了。它们成立了 .NET 基金会(红帽也是其中的一个成员),并且也加入了 Linux 基金会。 .NET 项目现在是以一个开源项目的形式在开发着。
  2. GitHub 已经成为了一个独特的社交网络,并将问题追踪器和分布式源码版本控制融入其中。

对于那些从闭源走过来的软件开发者来说,他们可能还不知道发生了什么。对于他们来说 ,开源就意味着“将业余时间的所有工作成果都免费开放”。

对于我们这些在过去十年创造了一家十亿美元的开源软件公司的人来说,参与开源以后就没有什么空闲的时间可言了。当然,为开源事业献身的好处也是很明显的,所得到的名誉是你自己的,并不隶属于某个公司。GitHub 是一个社交网络,在这个地方,你可以创建你的提交、你可以在你所专长的领域为一些全球性的组织做出贡献,你临时做的一些工作并不附属于所任职的公司。

聪明的人会利用这种工作环境。他们会贡献他们的补丁、 工单 ( issue ) 、评论给他们平时在工作中使用的语言和框架,比如 TypeScript、 .NET 和 Redux 。

他们也拥抱开源,并会尽可能多的开源他们的创新成果。甚至会提交他们的贡献给私有仓库。

GitHub 对平等居功至伟。比如说,你也许很难在澳大利亚得到一份来自印度的工作,但是,在 GitHub 上,却没有什么可以阻止你在印度跟澳大利亚的工作伙伴一起工作。

在过去十年里,想从红帽获得一个工作机会的方式很简单。你只需要在一些某些小的方面,与红帽的软件工程师在开源的项目上协作,然后当他们觉得你在某些方面做出了很多有价值的贡献,而且成为一个很好的工作伙伴时,那么你就可以申请一个红帽的工作机会了,或许他们会邀请你。

现在,在不同的技术领域,开源给了我们所有人同样的机会,随着开源在世界的各处都流行开来,这样的事情将会在不同的地方盛行开来。

在最近一个访谈中,Linux 和 git 的发明者 Linus Torvalds(在 GitHub 上有 49K 粉丝,0 关注),这么说,

“你提交了很多小补丁,而在某个时候项目的维护者开始信任你,在那一刻,你跟一般人不同的是,你不仅仅是提交了一些补丁,而是真正成为了这个组织里被信任的一部分。”

实际上你的名声存在于那个你被信任的网络。我们都知道,当你离开一家公司以后,你的人脉和名声可能会削弱,有的甚至会丢失。就好像,你在一个小村庄里生活了很长的一段时间,这里所有的人都会知道你。然而,当你离开这个村庄,来到一个新的地方,这个地方可能没人听说过你,更糟糕的是,没有人认识任何知道你的人。

你已经失去了一度和二度连接关系,甚至有可能会失去这三度连接关系(LCTT 译注:指六度连接理论)。除非你通过在会议或其他大型活动中演讲来建立自己的品牌,否则你通过在公司内部提交代码建立起来的信任早晚都会过去的,但是,如果你在 GitHub 上完成你的工作,这些东西依然全部都在,对这个信任网络的连接仍然可见。

首先会发生的事情就是,一些弱势群体可能会利用这个。包括像学生、新毕业生、移民者--他们可能会利用这个“去往”澳大利亚。

这将会改变目前的现状。以前的一些开发人员可能会有过人际网络突然中断的情况,开源的一个原则是精英——最好的创意、最多的提交、最多的测试,和最快的落实执行,等等。

它并不完美,当然也没有什么事情是完美的,不能和伙伴一起工作,在人们对你的印象方面也会大打折扣。红帽公司会开除那些不能和团队和谐相处的人,而在 GitHub 工作的这些员工,他们主要是和其它的贡献者之间的交流。

GitHub 不仅仅是一个代码仓库或是一个原始提交成员的列表,因为有些人总是用稻草人论点描述它。它是一个社交网络。我会这样说:

GitHub 有多少代码并不重要,重要的是有多少关于你代码的讨论。

GitHub 可以说是伴你而走的名声,并且在以后的 12 到 24 个月中,很多开发者使用它,而另外的一些依然并不使用,这将会形成一个很明显的差异。就像有电子邮件和没有电子邮件的区别(现在每个人都有电子邮件了),或者是有移动电话和没有移动电话的区别(现在每个人都有移动电话了),最终,绝大多数的人都会为开源工作,这将会是与别人的竞争中的一个差异化的优势。

但是现在,开发者的职业生涯已经被 GitHub 打乱了。

(题图: GitHub)


作者简介:

Josh Wulf - 我是 Just Digital People 的传奇招聘者,前红帽员工,CoderDojo 导师, Magikcraft.io 创始人之一,The JDP Internship 出品人——这是世界第一的软件开发真人秀,世界上最好的科技播客主持人,也是一位父亲。一直致力于昆士兰州的“硅经济”。


via: https://medium.com/@sitapati/the-impact-github-is-having-on-your-software-career-right-now-6ce536ec0b50

作者:Josh Wulf 译者:SysTick 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

使用 7 条简单的 Git 命令开始你的软件开发之旅

你是否曾经想知道如何学好 Git?你长期以来都是跌跌撞撞地在使用 Git。最终,你总需要掌握它的窍门。这就是我写这篇文章的原因,我将带你去启蒙之旅。这儿是我关于如何加快 Git 学习过程的基本指南。我将介绍 Git 的实际情况以及我使用最多的 7 条 Git 命令。本文主要针对有兴趣的开发人员和大学新生,他们需要关于 Git 的介绍以及如何掌握基础知识。


你可以往前继续阅读整篇文章,或者只读 TLDR; 部分,尽管这将使我很受伤。

TLDR;

在学习 Git 的过程中,请养成下面这些步骤的习惯:

  1. 随时使用 git status!
  2. 只更改那些你真正想更改的文件。
  3. git add -A 会是你的朋友。
  4. 随时使用命令 git commit -m "meaningful messages"。
  5. 做任何推送(push)之前先使用命令 git pull,但是这需要在你提交过一些更改之后。
  6. 最后,git push推送提交的更改。

良宵莫辜负

对任何开发人员来说,通常第一步都是选择一个广泛使用的地方托管他或她的代码库。那就是,GitHub。它是一切有关代码的聚集地。要理解 GitHub 的概念,你先需要知道什么是 Git。

Git 是一款基于命令行的版本控制软件,在 Windows 和 Mac 系统上也有几款可用的桌面应用。 Git 由 Linux 之父 Linus Torvalds 开发,Linus Torvalds 还是是计算机科学中最有影响力的人物之一。因为这一优势,Git 已经成为绝大多数软件开发人员关于共享和维护代码的标准。这一大段话,让我们将其细细道来。正如它的名字所说,版本控制软件 Git 让你可以预览你写过的代码的所有版本。从字面上来说, 开发人员的每个代码库都将永远存储在其各自的仓库中,仓库可以叫做任何名字,从 pineapple 到 express 都行。在此仓库开发代码的过程中,你将进行出无数次的更改,直到第一次正式发布。这就是版本控制软件如此重要的核心原因所在。它让作为开发人员的你可以清楚地了解对代码库进行的所有更改、修订和改进。从另外一个方面说,它使协同合作更容易,下载代码进行编辑,然后将更改上传到仓库。然而,尽管有了这么多好处,然而还有一件事可以锦上添花。你可以下载并使用这些文件,即使你在整个开发过程中什么事也没有做。

让我们回到文章的 GitHub 部分。它只是所有仓库的枢纽(hub),这些仓库可以存储在其中并在线浏览。它是一个让有着共同兴趣的人相聚的地方。

千里之行始于足下

OK,记住,Git 是一款软件,像任何其他软件一样,你首先需要安装它:

Git - 安装 Git,如果你希望从源代码安装 Git,你需要安装这些 Git 的依赖库: autotools —— 来自 git-scm.com

Tips:请点击上面的链接,然后按照说明开始。

完成了安装过程,很好。现在你需要在你的浏览器地址栏输入 github.com 访问该网站。如果你还没有帐号的话需要新创建一个帐号,这就是你的起舞之处。登录并创建一个新仓库,命名为 Steve ,没有什么理由,只是想要一个名为史蒂夫的仓库好玩而已。选中 “Initialize this repository with a README” 复选框并点击创建按钮。现在你有了一个叫做 Steve 的仓库。我相信你会为你自己感到自豪。

现在开始在使用 Git

现在是比较有趣的部分。你将把 Steve 克隆到你本地的机器上。可以把这个过程看作从 Github 上复制仓库到你的电脑上。点击 “clone or download” 按钮,你将看到一个类似下面这样的 URL:

https://github.com/yourGithubAccountName/Steve.git

复制这个 URL 并打开命令提示符窗口。现在输入并运行条命令:

git clone https://github.com/yourGithubAccountName/Steve.git

Abrakadabra!Steve 仓库已经被自动克隆到了你的电脑上。查看你克隆这个仓库的目录,你会看到一个叫做 Steve 的文件夹。这个本地的文件夹现在已经链接到了它的 “origin” ,也就是 GitHub 上的远程仓库。

记住这个过程,在你的软件开发工程人员的职业生涯中你一定会重复这个过程很多次的。完成所有这些准备工作之后,你就可以开始使用最普通且常用的 Git 命令了。

你现在已经开始在真实场景使用 Git 了

找到 Steve 目录并在该目录中打开命令提示符窗口,运行下面的命令:

git status

这会输出你的工作目录的状态,让你知道所有你编辑过的文件。这意味着它显示了远程库中和本地工作目录中之间的文件差异。status 命令被用来作为 commit 的模版,我将在这篇教程后面进一步谈论 commit 。简单的说,[git status][1] 告诉你你编辑过哪些文件,以给你一个你想要上传到远程库的概述。

但是,在你做任何上传之前,你首先需要做的是选择你需要发送回远程库的文件。使用下面命令完成:

git add

接着在 Steve 目录新建一个文本文件,可以取一个好玩的名字 pineapple.txt。在这个文件里面随便写些你想写的内容,返回命令提示符,然后再次输入 git status。现在,你将看到这个文件以红色出现在标记 “untracked files” 下面。

On branch master
Your branch is up-to-date with 'origin/master'.
Untracked files:
  (use "git add <file>..." to include in what will be commited)

pineapple.txt

下一步就是将它添加到暂存区(staging)。暂存区可以看作是这样的一个环境:你做过的所有更改在提交时都将捆绑为一个更改而被提交。现在,你可以将这个文件加入暂存区:

git add -A

-A 选项意味着所有你更改过的文件都会被加到暂存区等待提交。然而, git add 非常灵活,它也可以像这样一个文件一个文件的添加:

git add pineapple.txt

这种方法让你有能力选择你想要暂存的每一个文件,而不用担心加入那些你不想改变的东西。

再次运行 git status,你会看到如下输出:

On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

new file:   pineapple.txt

准备好提交更改了吗?开始吧。

git commit -m "Write your message here"

Git commit 命令会将存储在暂存区中的文件和来自用户的用于描述更改的日志信息一起存储在一个新的地方。-m选项加入了写在双引号内的信息。

再次检查状态,你会看到:

On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

所有的更改现在都被加入到一次提交当中了,同时会有一条与你所做相关的信息。现在你可以用 git push 将这次提交推送到远程库 “origin”了。这条命令就像字面意义所说,它会把你提交的更改从本地机器上传到 GitHub 的远程仓库中。返回到命令提示符,然后运行:

git push

你会被要求输入你的 GitHub 帐号和密码,之后你会看到类似下面的这些内容:

Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 280 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/yourGithubUserName/Steve.git
   c77a97c..08bb95a  master -> master

就是这样。你已经成功上传了你本地的更改。看看你在 GitHub 上的仓库,你会看到它现在包含了一叫做 pineapple.txt 的文件。

如果你是一个开发小组的一员呢?如果他们都推送提交到 “origin”,将会发生什么?这就是 Git 真正开始发挥它的魔力的时候。你可以使用一条简单的命令轻松地将最新版本的代码库 pull 到你本地的机器上:

git pull

但是 Git 也有限制:你需要有相匹配的版本才能推送到 “origin”。这意味着你本地的版本需要和 origin 的版本大致一样。当你从 “origin” 拉取(pull)文件时,在你的工作目录中不能有文件,因为它们将会在这个过程中被覆盖。因此我给出了这条简单的建议。在学习 Git 的过程中,请养成下面这些步骤的习惯:

  1. 随时使用 git status!
  2. 只更改那些你真正想更改的文件。
  3. git add -A 会是你的朋友。
  4. 随时使用命令 git commit -m "meaningful messages"。
  5. 做任何推送(push)之前先使用命令 git pull,但是这需要在你提交过一些更改之后。
  6. 最后,git push推送提交的更改。

嘿!你还在看这篇文章吗?你已经看了很久了,休息一下吧!

休息好了吗?好的!让我们来处理一些错误。如果你不小心更改了一些你本不应该更改的文件后怎么办呢?不需要担心,只需要使用 git checkout。让我们在文件 pineapple.txt 里更改一些内容:在文件中加入一行,比方说,“Steve is mega-awesome!” 。然后保存更改并用 git status 检查一下:

On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

modified:   pineapple.txt

no changes added to commit (use "git add" and/or "git commit -a")

正如预料的那样,它已经被记录为一次更改了。但是,假如 Steve 实际上并不是很优秀呢?假如 Steve 很差劲呢?不用担心!最简单的还原更改的方式是运行命令:

git checkout -- pineapple.txt

现在你会看到文件已经恢复到了先前的状态。

但是假如你玩砸了呢?我是说,事情已经变得混乱,并且需要把所有东西重置到与 “origin” 一样的状态。也不需要担心,在这种紧急情况下我们可以享受 Git 的美妙之处:

git reset --hard

git reset 命令和 --hard 选项一起可以抛弃自上次提交以来的所有更改,有些时候真的很好用。


最后,我想鼓励你尽可能多地使用 Git。这是能够熟练使用它的最好学习方式。除此之外,养成阅读 Git 文档的习惯。一开始可能会有些云里雾里,但是过段时间后你就会明白它的窍门了。

希望你们(小伙子和姑娘们)读这篇文章的时候会和我写它时一样的开心。如果你认为这篇文章对别人有用,你尽可以与别人分享它。或者,如果你喜欢这篇文章,你可以在下面点下赞以便让更多的人看到这篇文章。


via: https://hackernoon.com/how-to-master-the-art-of-git-68e1050f3147

作者:Adnan Rahić 译者:zhousiyu325 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

很庆幸,我们当初选择 Markdown 作为用户在 GitHub 上托管内容的标记语言,它为用户提供了强大且直接的方式 (不管是技术的还是非技术的) 来编写可以很好的渲染成 HTML 的纯文本文档。

然而,其最主要的限制,就是缺乏在最模糊的语言细节上的标准。比如,使用多少个空格来进行行缩进、两个不同元素之间需要使用多少空行区分、大量繁琐细节往往造成不同的实现:相似的 Markdown 文档会因为选用的不同的语法解析器而渲染成相当不同的呈现效果。

五年前,我们在 Sundown 的基础之上开始构建 GitHub 自定义版本的 Markdown —— GFM ( GitHub 风格的 Markdown GitHub Flavored Markdown ),这是我们特地为解决当时已有的 Markdown 解析器的不足而开发的一款解析器。

今天,我们希望通过发布 GitHub 风格的 Markdown 的正式语法规范及其相应的参考实现来改善现状。

该正式规范基于 CommonMark,这是一个雄心勃勃的项目,旨在通过一个反映现实世界用法的方式来规范目前互联网上绝大多数网站使用的 Markdown 语法。CommonMark 允许人们以他们原有的习惯来使用 Markdown,同时为开发者提供一个综合规范和参考实例,从而实现跨平台的 Markdown 互操作和显示。

规范

使用 CommonMark 规范并围绕它来重新加工我们当前用户内容需要不少努力。我们纠结的主要问题是该规范 (及其参考实现) 过多关注由原生 Perl 实现支持的 Markdown 通用子集。这还不包括那些 GitHub 上已经在用的扩展特性。最明显的就是缺少 表格 ( tables ) 、 删除线 ( strikethrough ) 、 自动链接 ( autolinks ) 和 任务列表 ( task lists ) 的支持。

为完全描述 GitHub 的 Markdown 版本 (也称为 GFM),我们必须要要正式定义这些特性的的语法和语意,这在以前从未做过。我们是在现存的 CommonMark 规范中来完成这一项工作的,同时还特意关注以确保我们的扩展是原有规范的一个严格且可选的超集。

当评估 GFM 规范 的时候,你可以清楚的知道哪些是 GFM 特定规范的补充内容,因为它们都高亮显示了。并且你也会看到原有规范的所有部分都保持原样,因此,GFM 规范能够与任何其他的实现保持兼容。

实现

为确保我们网站中的 Markdown 渲染能够完美兼容 CommonMark 规范,GitHub 的 GFM 解析器的后端实现基于 cmark 来开发,这是 CommonMark 规范的一个参考实现,由 John MacFarlane 和许多其他的 出色的贡献者 开发完成。

就像规范本身那样,cmark 是 Markdown 的严格子集解析器,所以我们还必须在现存解析器的基础上完成 GitHub 自定义扩展的解析功能。你可以通过 cmark 的分支 来查看变更记录;为了跟踪不断改进的上游项目,我们持续将我们的补丁变基到上游主线上去。我们希望,这些扩展的正式规范一旦确定,这些补丁集同样可以应用到原始项目的上游变更中去。

除了在 cmark 分支中实现 GFM 规范特性,我们也同时将许多目标相似的变更贡献到上游。绝大多数的贡献都主要围绕性能和安全。我们的后端每天都需要渲染大量的 Markdown 文档,所以我们主要关注这些操作可以尽可能的高效率完成,同时还要确保那些滥用的恶意 Markdown 文档无法攻击到我们的服务器。

第一版使用 C 语言编写的解析器存在严重的安全隐患:通过足够深度的特殊 Markdown 元素的嵌套,它可能造成堆栈溢出 (甚至有时候可以运行任意代码)。而 cmark 实现,就像我们之前设计的解析器 Sundown,从一开始设计就考虑到要抵御这些攻击。其解析算法和基于 AST 的输出可以优雅的解决深层递归以及其他的恶意文档格式。

cmark 在性能方面则是有点粗糙:基于实现 Sundown 时我们所学到的性能技巧,我们向上游贡献了许多优化方案,但除去所有这些变更之外,当前版本的 cmark 仍然无法与 Sundown 本身匹敌:我们的基准测试表明,cmark 在绝大多数文档渲染的性能上要比 Sundown 低 20% 到 30%。

那句古老的优化谚语 最快的代码就是不需要运行的代码 ( the fastest code is the code that doesn’t run ) 在此处同样适用:实际上,cmark 比 Sundown 要多进行一些操作。在其他的功能上,cmark 支持 UTF8 字符集,对参考的支持、扩展的接口清理的效果更佳。最重要的是它如同 Sundown 那样,并不会将 Markdown 翻译成 HTML。它实际上从 Markdown 源码中生成一个 AST (抽象语法树,Abstract Syntax Tree),然后我们就看将之转换和逐渐渲染成 HTML。

如果考虑下我们在 Sundown 的最初实现 (特别是文档中关于查询用户的 mention 和 issue 引用、插入任务列表等) 时的 HTML 语法剖析工作量,你会发现 cmark 基于 AST 的方法可以节约大量时间 和 降低我们用户内容堆栈的复杂度。Markdown AST 是一个非常强大的工具,并且值得 cmark 生成它所付出的性能成本。

迁移

变更我们用户的内容堆栈以兼容 CommonMark 规范,并不同于转换我们用来解析 Markdown 的库那样容易:目前我们在遇到最根本的障碍就是由于一些不常用语法 (LCTT 译注:原文是 the Corner,作为名词的原意为角落、偏僻处、窘境,这应该是指那些不常用语法),CommonMark 规范 (以及有歧义的 Markdown 原文) 可能会以一种意想不到的方式来渲染一些老旧的 Markdown 内容。

通过综合分析 GitHub 中大量的 Markdown 语料库,我们断定现存的用户内容只有不到 1% 会受到新版本实现的影响:我们是通过同时使用新 (cmark,兼容 CommonMark 规范) 旧 (Sundown) 版本的库来渲染大量的 Markdown 文档、标准化 HTML 结果、分析它们的不同点,最后才得到这一个数据的。

只有 1% 的文档存在少量的渲染问题,使得换用新实现并获取其更多出看起来是非常合理的权衡,但是是根据当前 GitHub 的规模,这个 1% 是非常多的内容以及很多的受影响用户。我们真的不想导致任何用户需要重新校对一个老旧的问题、看到先前可以渲染成 HTML 的内容又呈现为 ASCII 码 —— 尽管这明显不会导致任何原始内容的丢失,却是糟糕的用户体验。

因此,我们想出相应的方法来缓和迁移过程。首先,第一件我们做的事就是收集用户托管在我们网站上的两种不同类型 Markdown 的数据:用户的评论 (比如 Gist、issue、PR 等)以及在 git 仓库中的 Markdown 文档。

这两种内容有着本质上的区别:用户评论存储在我们的数据库中,这意味着他们的 Markdown 语法可以标准化 (比如添加或移除空格、修正缩进或则插入缺失的 Markdown 说明符,直到它们可正常渲染为止)。然而,那些存储在 Git 仓库中的 Markdown 文档则是 根本 无法触及,因为这些内容已经散列成为 Git 存储模型的一部分。

幸运的是,我们发现绝大多数使用了复杂的 Markdown 特性的用户内容都是用户评论 (特别是 issue 主体和 PR 主体),而存储于仓库中的文档则大多数情况下都可以使用新的和旧的渲染器正常进行渲染。

因此,我们加快了标准化现存用户内容的语法的进程,以便使它们在新旧实现下渲染效果一致。

我们用以文档转换的方法相当实用:我们那个旧的 Markdown 解析器, Sundown,更多的是扮演着翻译器而非解析器的角色。输入 Markdown 内容之后,一系列的语意回调就会把原始的 Markdown 内容转换为目标语言 (在我们的实际使用中是 HTML5) 的对应标记。基于这一设计方法,我们决定使用语意回调让 Sumdown 将原始 Markdown 转换为兼容 CommonMark 的 Markdown,而非 HTML。

除了转换之外,这还是一个高效的标准化过程,并且我们对此信心满满,毕竟完成这一任务的是我们在五年前就使用过的解析器。因此,所有的现存文档在保留其原始语意的情况下都能够进行明确的解析。

一旦升级 Sundown 来标准化输入文档并充分测试之后,我们就会做好开启转换进程的准备。最开始的一步,就是对所有新用户内容切换到新的 cmark 实现上,以便确保我们能有一个有限的分界点来进行过渡。实际上,几个月前我们就为网站上所有 新的 用户评论启用了 CommonMark,这一过程几乎没有引起任何人注意 —— 这是关于 CommonMark 团队出色工作的证明,通过一个最具现实世界用法的方式来正式规范 Markdown 语言。

在后端,我们开启 MySQL 转换来升级替代所有 Markdown 用户内容。在所有的评论进行标准化之后,在将其写回到数据库之前,我们将使用新实现来进行渲染并与旧实现的渲染结果进行对比,以确保 HTML 输出结果视觉上感觉相同,并且用户数据在任何情况下都不会被破坏。总而言之,只有不到 1% 的输入文档会受到标准进程的修改,这符合我们的的期望,同时再次证明 CommonMark 规范能够呈现语言的真实用法。

整个过程会持续好几天,最后的结果是网站上所有的 Markdown 用户内容会得到全面升级以符合新的 Markdown 标准,同时确保所有的最终渲染输出效果对用户视觉上感觉相同。

结论

从今天 (LCTT 译注:原文发布于 2017 年 3 月 14 日,这里的今天应该是这个日期) 开始, 我们同样为所有存储在 Git 仓库中的 Markdown 内容启动 CommonMark 渲染。正如上文所述,所有的现存文档都不会进行标准化,因为我们所期望中的多数渲染效果都刚刚好。

能够让在 GitHub 上的所有 Markdown 内容符合一个动态变化且使用的标准,同时还可以为我的用户提供一个关于 GFM 如何进行解析和渲染 清晰且权威的参考说明,我们是相当激动的。

我们还将致力于 CommonMark 规范,一直到在它正式发布之前消除最后一个 bug。我们也希望 GitHub.com 在其 1.0 规范发布之后可以进行完美兼容。

作为结束,以下为想要学习 CommonMark 规范或则自己来编写实现的朋友提供一些有用的链接。


译者简介:

GHLandy —— 生活中所有欢乐与苦闷都应藏在心中,有些事儿注定无人知晓,自己也无从说起。


via: https://githubengineering.com/a-formal-spec-for-github-markdown/

作者:Yuki IzumiVicent Martí 译者:GHLandy 校对:jasminepeng

本文由 LCTT 原创编译,Linux中国 荣誉推出

对于大多数开源项目来讲, 问题追踪系统 ( Issue-tracking system ) 是至关重要的。虽然有非常多的开源工具提供了这样的功能,但是大量项目还是选择了 GitHub 自带的 问题追踪器 ( Issue Tracker ) 。

它结构简单,可以让其他人可以非常轻松地参与进来,但这才仅仅是开始。

如果没有适当的处理,你的 储存库 ( repository ) 会变得很庞大,挤满重复的问题单、模糊不明的特性需求单、含混的 bug 报告单。项目维护者会被大量工作压得喘不过气来,新的贡献者也搞不清楚项目当前的工作重点是什么。

接下来,我们一起研究下,如何玩转 GitHub 的问题单。

问题单就是用户的故事

我的团队曾经和开源专家 Jono Bacon 做过一次对话,他是 《社区艺术》 ( The Art of Community ) 一书的作者、一位战略顾问、前 GitHub 社区总监。他告诉我们,高质量的问题单是项目成功的关键。有些人把问题单仅仅看作是一堆你不得不去处理的问题列表,但是如果这些问题单管理完善,进行了分类并打上标签,会令人意想不到的提升我们对代码和社区的了解程度,也让我们更清楚问题的关键点在哪里。

“在提交问题单时,用户不太会有耐心或者有兴趣把问题的细节描述清楚。在这种情况下,你应当努力花最短的时间,尽量多的获取有用的信息。”,Jono Bacon 说。

统一的问题单模板可以大大减轻项目维护者的负担,尤其是开源项目的维护者。我们发现,让用户讲故事的方法总是可以把问题描述的非常清楚。用户讲故事时需要说明“是谁,做了什么,为什么而做”,也就是:我是【何种用户】,为了【达到何种目的】,我要【做何种操作】。

实际操作起来,大概是这样的:

我是一名顾客,我想购买东西,所以我想创建个账户。

我们建议,问题单的标题始终使用这样的用户故事形式。你可以设置问题单模板来保证一致性。

问题单模板让特性需求单保持统一的形式

这个做法的核心点在于,问题单要清晰的呈现给它涉及的每一个人:它要尽量简单的指明受众(或者说用户),操作(或者说任务),和输出(或者说目标)。不过,不需要过分拘泥于这个模板,只要能把故事里的是什么事情或者是什么原因说清楚,就达到目的了。

高质量的问题单

问题单的质量是参差不齐的,这一点任何一个开源软件的贡献者或维护者都能证实。在《The Agile Samurai》中概述过一个良好的问题单所应具备的素质。

好的问题单尽量满足如下条件:

  • 客户价值所在
  • 避免使用术语或晦涩的文字,就算不是专家也能看懂
  • 可以切分,也就是说我们可以逐步解决问题
  • 尽量跟其他问题单没有瓜葛,依赖其它问题会降低处理的灵活性
  • 可以协商,也就说我们有好几种办法达到目标
  • 问题足够小,可以非常容易的评估出所需时间和资源
  • 可衡量,我们可以对结果进行测试

不满足上述条件的问题单呢? 要有约束

如果一个问题单很难衡量,或者很难在短时间内完成,你也一样有办法搞定它。有些人把这种办法叫做“约束”(constraints)。

例如,“这个产品要快”,这种问题单不符合故事模板,而且是没办法协商的。多快才是快呢?这种模糊的需求没有达到“好问题单”的标准,但是如果你进一步定义一下,例如“每个页面都需要在 0.5 秒内加载完”,那我们就能更轻松地解决它了。我们可以把“约束”看作是成功的标尺,或者要实现的里程碑。每个团队都应该定期的对“约束”进行测试。

问题单里面有什么?

敏捷方法中,用户故事里通常要包含验收指标或者标准。在 GitHub 里,建议大家使用 markdown 格式的清单来概括解决这个问题单需要完成的任务。优先级越高的问题单应当包含更多的细节。

比如说,你打算提交一个关于新版网站主页的问题单。那这个问题单的子任务列表可能就是这样的:

使用 markdown 的清单把复杂问题拆分成多个部分

在必要的情况下,你还可以链接到其他问题单,以进一步明确任务。(GitHub 里做这个挺方便的)

将特性定义的越细化,越容易跟踪进度、测试,最终能更高效的发布有价值的代码。

以问题单的形式收到到问题所在后,还可以用 API 更深入的了解软件的健康度。

“在统计问题单的类型和趋势时,GitHub API 可以发挥巨大作用”,Bacon 告诉我们,“如果再做些数据挖掘工作,你就能发现代码里的问题点、社区里的活跃成员,或者其他有用的信息。”

有些问题单管理工具提供的 API 可以提高额外信息,比如预估时间或者历史进度。

团队协同一致

团队决定使用某种问题单模板后,如何让所有人都照做?存储库里的 ReadMe.md 其实也可以是你们项目的 “How-to” 文档。这个文档应描述清楚这个项目是做什么的(最好是用可以搜索的语言),以及其他贡献者应当如何参与进来(比如提交需求单、bug 报告、建议,或者直接贡献代码)。

在 ReadMe 文件里增加清晰的说明,供新协作者参考

ReadMe 文件是提供“问题单指引”的完美场所。如果希望特性需求单遵循“用户讲故事”的格式,那就把格式写在 ReadMe 里。如果使用某种跟踪工具来管理待办事项,那就标记在 ReadMe 里,这样别人也能看到。

“问题单模板、合理的标签、提交问题单的指导文档、确保问题单被分类并及时回应,这些对于开源项目都至关重要”,Bacon 说。

记住一点:这不是为了完成工作而做的工作。这是让其他人更轻松的发现、了解、融入你的社区而设立的规则。

"关注社区的成长,不仅要关注参与开发者的的数量增长,也要关注那些在问题单上帮助我们的人,他们让问题单更加明确、保持更新,这是活跃沟通和高效解决问题的力量源泉",Bacon 说。


via: https://opensource.com/life/16/7/how-take-your-projects-github-issues-good-great

作者:Matt Butler 译者:echoma 校对:jasminepeng

本文由 LCTT 原创翻译,Linux中国 荣誉推出

GitHub 又发布了一年一度的章鱼猫观察报告。在这个报告中,分别对开源和社区做了一些有趣的统计,现将其中一些有趣的数据和趋势撷取出来分享给大家。完整的报告请移步此处。

GitHub 上最流行的开源项目

从让阿波罗 11 号登月的代码到开源课程,过去十二个月中,GitHub 上又涌现了一大批开源项目。以下是最流行的(得到星标最多)项目:

最流行的开源项目

其中使用最多的开源许可证是:MIT、Apache-2.0 和 GNU General Public License v3.0。

GitHub 上最爱用的编程语言

GitHub 上存放的开源项目使用了多达 316 种不同的编程语言,其中在过去十二月中提交的 PR( 拉取请求 ( Pull Request ) ,用于向项目提交补丁) 使用最多的前 15 种编程语言是(其中的数字是 PR 数量):

PR 中最流行的 15 种语言

PR 中最流行的语言居然是 JavaScript,是因为 JavaScript 比较容易么?而且 JavaScript、C# 和 Go 语言的 PR 增长率达到了两倍,甚至,Swift 和 TypeScript 虽然总量不多,但是增长率达到了 3.5 倍。

贡献者的活跃程度

“ 活跃 ( Active ) ”是指有过代码提交、写了备注、被星标和 问题汇报 ( issue ) 等行为。

这十二个月以来,有 580 万以上的活跃用户、33 万以上的活跃组织、1.9 亿以上的活跃仓库、1 千万以上的活跃问题汇报。

“ 贡献者 ( contributors ) ”是指对项目/仓库推送了代码、对打开或评论了问题和 PR 的人,按照贡献者对项目和组织进行排名:

开源贡献者最多的前十个仓库

其中贡献者最多的仓库是 Font-Awesome 项目,这是一个图标字体的项目,不太理解为何有这么多的贡献者。其次是 docker 和 npm。

开源贡献者最多的组织

开源贡献者最多的组织是微软,超过了 Facebook、docker,以及谷歌。看来微软这一年确实是在开源方面下了死力。

被最多分支的仓库

仓库被 分支 ( fork ) 的越多代表了对它感兴趣、甚至会参与到开发中的人越多。这个排名第一的 datasharing 是个啥项目,我去看看——居然是一篇文章……好吧,让我看看第二个 Spoon-Knife,这,是章鱼猫的一个教人如何分支仓库的例子……那么第三个 ProgrammingAssignment2 ,哎,也是一个课程上用的例子……

好吧,我收回之前对分支的看法,就不能有个“正常”点的仓库嘛?

还好,第四 bootstrap 和第五 tensorflow 都是比较正常的开源项目。总之,项目流行不流行,不要看分支数量了。

被最多用户评审过代码的仓库

这里的 代码评审者 ( reviewers ) 指的是对修改过的代码进行过评论的人,这也代表贡献者对仓库的关注度。好吧。我除了对第一名 homebrew 有点不解,其它的几名都觉得还算正常。

GitHub 的新增用户

GitHub 已经有超过 520 万的用户和超 30 万的组织。这十二月以来,有超过 81 万的人发起了人生第一个 PR,更有 280 万人创造了他自己的第一个仓库。

新用户注册增长最多的国家

而中国,是新用户注册增长最多的国家,基本上翻了一番。

GitHub 上的组织

GitHub 上已经有超过 8 千万的 PR,而这些 PR 中有超过 85% 的来自于组织。在 GitHub 上以组织形式活动的除了商业性组织以外,很多大公司也在其企业的开发中采用了 GitHub Enterprise ,其中不乏财富50强里面公司。

总结

报告就解读到这里,详细的图文并茂的报告,请移步 GitHub。