为开源做贡献：以Dillinger为例

If you've tried to get a job as a programmer, you must have noticed how many companies ask for GitHub profiles, active Open Source efforts and general proliferation of your work.

如果您想找到一名程序员工作，那么您一定已经注意到有多少公司要求提供GitHub个人资料，积极的开源努力以及工作的普遍发展。

The more you do, the more you're worth. Unfortunately, they look at quantity over quality all too often.

您做得越多，您就越值钱。 不幸的是，他们总是过于看重数量而不是质量。

But as Napoleon Hill said – if you can't do great things, do small things in a great way.

但是正如拿破仑·希尔(Napoleon Hill)所说的那样- 如果您不能做伟大的事情，那就以伟大的方式做小事情 。

问题 (The Problem)

In this article, we'll contribute to a popular open source MarkDown editor – Dillinger. Dillinger is an online text editor which lets you type MarkDown and preview it in the other part of the window at the same time, displaying it just as it will look when rendered into HTML. As the PHP editor for SitePoint, I use it quite often, but one of the gripes I have with it is the "Show HTML" function which, when selected, summons a popup with a simple div element which contains the HTML version (in text form) of our MarkDown content. Why is this a problem? Because I then need to manually select text in a div, and if the content is long enough, I need to do so while scrolling down. Needless to say, this becomes rather tedious fast.

在本文中，我们将为流行的开源MarkDown编辑器Dillinger做出贡献。 Dillinger是一个在线文本编辑器，可让您键入MarkDown并同时在窗口的另一部分中预览它，就像将其呈现为HTML时一样，将其显示出来。 作为SitePointPHP编辑器，我经常使用它，但是我最讨厌的一个就是“显示HTML”功能，当选中该功能时，它会弹出一个带有包含HTML版本的简单div元素的弹出窗口(以文本形式显示)形式)。 为什么这是个问题？ 因为然后我需要在div中手动选择文本，并且如果内容足够长，则需要在向下滚动时进行选择。 不用说，这变得非常乏味。

解决方案 (The Solution)

The ideal solution would be adding a "Copy HTML" button which would simply place the code in the clipboard, without requiring any kind of selection. However, this would require Flash and in today's ridiculously biased anti-Flash world, this simply isn't an option. Instead, let's opt for a compromise.

理想的解决方案是添加“复制HTML”按钮，该按钮将代码简单地放置在剪贴板中，而无需进行任何选择。 但是，这将需要Flash，而在当今荒谬的反Flash世界中，这根本不是一个选择。 相反，让我们选择一个折衷方案。

We'll turn the div containing our HTML code into a textarea that's in select-all mode by default. All anyone has to do then is just press CTRL+C, and the HTML content is in the clipboard. Even if selection/focus is lost, it's easy to select-all again just by placing the cursor inside the field and pressing CTRL+A.

我们将包含HTML代码的div转换为默认情况下处于全选模式的文本区域。 任何人要做的就是按CTRL + C，HTML内容在剪贴板中。 即使失去选择/焦点，也只需将光标放在字段中并按CTRL + A，就很容易再次选择所有内容。

制备 (Preparation)

When contributing to an Open Source project, the original author often leaves hints and tips on how to do it. Sometimes it's in the README of a project, sometimes a separate file called CONTRIBUTING is made. On Dillinger, there is no such instruction (for now). Only an installation procedure is described, and that's good enough for us.

在为开放源代码项目做贡献时，原始作者经常会留下一些提示和技巧。 有时它在项目的自述文件中，有时会制作一个单独的文件，称为CON​​TRIBUTING。 在Dillinger上，暂时没有这样的说明。 仅描述了安装过程 ，这对我们已经足够了。

To begin, we first need to fork the project. Forking, if you're unfamiliar with the term, is the process of copying a repository to your own account in order to expand on it or make your own version. When you make a fork and add something into it, you have the option of sending a Pull Request to the original author. This makes the author know you have proposed an update to the project, and would like it included in the main repository, so that all future forks of that repository also contain your newly added feature/fix. We fork the repo, and it can now also be found here. Feel free to follow along, though by the time this article is published, the pull request this tutorial will end with will be accepted and integrated. Still, it's a good exercise in setting up Dillinger locally!

首先，我们首先需要创建项目。 如果您不熟悉分叉，则它是将存储库复制到您自己的帐户以扩展帐户或创建自己的版本的过程。 制作叉子并向其中添加一些东西时，可以选择将“拉取请求”发送给原始作者。 这使作者知道您已经提出了对该项目的更新，并且希望将其包含在主存储库中，以便该存储库的所有将来的分支也都包含您新添加的功能/修复程序。 我们分叉仓库，现在也可以在这里找到它。 随时随地，尽管在发布本文时，本教程将以结尾的拉取请求将被接受并集成。 尽管如此，在本地设置Dillinger还是一个很好的练习！

Before proceeding, please make sure you have the latest nodeJS installed.

在继续之前，请确保已安装最新的nodeJS 。

Using your command line, cd into the folder where you keep your projects and run the installation steps. We won't be using the plugins, so there's no need to configure those. Now, when you visit http://localhost:8080, Dillinger should be running locally.

使用命令行， cd进入保存项目并运行安装步骤的文件夹。 我们将不会使用这些插件，因此无需配置它们。 现在，当您访问http：// localhost：8080时 ，Dillinger应该在本地运行。

将您的仓库连接到原始仓库 (Connecting your repo to the original)

If you intend to hack on Dillinger later, you should probably set up an upstream remote to the original repo. This is done so you can frequently pull new updates from the original into your own project. Do the following in the app's folder:

如果您打算稍后入侵Dillinger，则可能应设置原始回购的上游远程服务器。 这样做是为了使您可以经常将新的更新从原始文件中拉到您自己的项目中。 在应用程序的文件夹中执行以下操作：

git remote add --track master upstream [GIT URL HERE]

What this means in humanese is "Set up another source of code for this project at [URL] and track it's master branch". Fetching the code is done with the fetch command, when necessary (git fetch upstream) and then you can merge it into your own project with either the merge or the rebase command:

用人工语言来说，这意味着“在[URL]上为此项目设置另一个代码源并跟踪它的master分支”。 必要时使用fetch命令完成代码的获取( git fetch upstream )，然后可以使用merge或rebase命令将其合并到自己的项目中：

git merge upstream/master

# or

git rebase upstream/master

Git rebase overwrites your branch's history, that's the only difference in this case, but is actually preferred by most developers due to the cleanliness of pull requests it allows – a clean history is more readable. Like this post says:

Git rebase会覆盖分支的历史记录，这是这种情况的唯一区别，但是由于它允许的拉取请求的整洁性，因此实际上大多数开发人员都喜欢它，因为整洁的历史记录更具可读性。 像这样的帖子说：

The git rebase <upstream> command rewinds back to a common ancestry point of <upstream> and the current branch and replays the current branch's changes on top of the newest <upstream>.

git rebase <upstream>命令后退到<upstream>和当前分支的公共祖先点，并在最新的<upstream>上重放当前分支的更改。

In other words – whenever you can, use rebase.

换句话说–尽可能使用rebase。

We don't need any of these commands for now, just keep them handy for future reference on how to update the fork of a GitHub repo.

目前我们不需要任何这些命令，只需将它们放在方便位置以备将来参考，以了解如何更新GitHub存储库的fork 。

分支和固定 (Branching and fixing)

To contribute to a project, we first need to create a new branch because

为了对项目做出贡献，我们首先需要创建一个新分支，因为

1. Hacking on the master branch is just silly
   在master分支上进行黑客攻击只是愚蠢的
2. GitHub has a one pull request per branch policy
   GitHub每个分支机构策略都有一个请求请求

Let's do that right now.

现在就开始吧。

git branch showhtml-fix
git checkout showhtml-fix

We are now in our own branch. Let's start hacking!

我们现在在自己的分支机构中。 让我们开始骇客吧！

Open the project in your favorite code editor (I use PhpStorm since it's basically WebStorm with PHP support built in) and look at the following relevant files:

在您喜欢的代码编辑器中打开项目(我使用PhpStorm，因为它基本上是内置了PHP支持的WebStorm)，然后查看以下相关文件：

• views/nav.esj

  views/nav.esj

• public/js/dillinger.js

  public/js/dillinger.js

.ejs is the extension for Express view templates, and not being familiar with it shouldn't concern you.

.ejs是Express视图模板的扩展，不熟悉它就不会引起您的注意。

In nav.ejs, you'll find the following code near the top:

在nav.ejs ，您将在顶部附近找到以下代码：

<div id="myModalBody" class="modal-body">
        <pre>
          <div id="myModalBody" class="modal-body">
          </div>
        </pre>
    </div>

This is the modal window that shows the HTML text content when we click "Show HTML". You can find this out by yourself by clicking Inspect Element on the modal window when it shows up in Dillinger. After looking through the entire project for other uses of "#myModalBody" (PhpStorm and WebStorm have a "Find In Path" option which searches the entire project for the uses of a phrase), we conclude that its only use is Show HTML, and thus, we can safely change it. Change it to the following:

这是一个模式窗口，当我们单击“显示HTML”时显示HTML文本内容。 您可以通过在Dillinger中显示的模态窗口中单击“检查元素”来自己找到它。 在整个项目中查找“ #myModalBody”的其他用途(PhpStorm和WebStorm具有“查找路径”选项后，该选项会在整个项目中搜索短语的使用)之后，我们得出结论，它的唯一用途是Show HTML，并且因此，我们可以安全地对其进行更改。 将其更改为以下内容：

<div id="myModalBody" class="modal-body">
        <textarea id="modalBodyText"></textarea>
    </div>

Also, find the function showHTML in dillinger.js and replace the function _doneHandler:

另外，在dillinger.js找到函数showHTML并替换函数_doneHandler ：

function _doneHandler(jqXHR, data, response){
      // console.dir(resp)
      var resp = JSON.parse(response.responseText)
      $('#myModalBody').text(resp.data)
      $('#myModal').modal()
    }

with this content:

具有以下内容：

function _doneHandler(jqXHR, data, response){
            var resp = JSON.parse(response.responseText)
            $('#modalBodyText').val(resp.data);
            $('#myModal').modal()
        }

Refresh, and now we have… this?

刷新，现在我们有……这个？

Not quite what we were looking for, huh? That's ok, we can "Inspect Element" on the text field, and do some on-the-fly alterations until we get something we're happy with.

不是我们想要的，是吗？ 没关系，我们可以在文本字段上“检查元素”，并进行一些即时更改，直到我们满意为止。

The first thing we do, is give the textarea a width and height of 100%.

我们要做的第一件事是使textarea的宽度和高度为100％。

Hm, this didn't really do what we wanted. This is because height is inherited from the parent element – 100% means 100% of the parent's height. We'll need to edit the containing div's style as well.

嗯，这并没有真正做到我们想要的。 这是因为height是从父元素继承的-100％表示父元素高度的100％。 我们还需要编辑包含div的样式。

We'll give it an absolute position, so we can absolutely position it inside the modal window. Then, we'll give it a width of 565px, because the entire modal window is of a fixed 600px width, and 565px fits quite nicely. To stretch it from the theoretical top of the modal body, to the bottom, we use fixed values instead of percentages, making sure we only define an offset from the edges, and everything in between is filled out automatically. We give it the top value of 45px (enough to show the header of the modal, the close button and the divider line), and a bottom value of 10px, enough to simulate a nice margin. Suddenly, we have this:

我们将为其指定绝对位置，因此我们可以将其绝对定位在模态窗口内。 然后，将其宽度设置为565px，因为整个模式窗口的宽度固定为600px，并且565px非常适合。 为了将其从模态主体的理论顶部延伸到底部，我们使用固定值而不是百分比，确保只定义了与边缘的偏移量，并且自动填充了它们之间的所有内容。 我们给它的最高值是45px(足以显示模态的标题，关闭按钮和分隔线)和最低值10px，足以模拟一个不错的边距。 突然，我们有了这个：

If you want, add background-color: transparent to the textarea to get rid of the red background.

如果需要，可以在文本区域中添加background-color: transparent以消除红色背景。

Now that we know what we need to do with the CSS to get what we want, let's implement it into the project's code. Open modals.styl (.styl is a Stylus file) and paste in the following CSS:

既然我们知道要使用CSS来获取所需的内容，现在将其实现到项目代码中。 打开modals.styl (.styl是Stylus文件)并粘贴在以下CSS中：

#myModalBody {
    position: absolute;
    width: 565px;
    top: 45px;
    bottom: 10px;
}

#modalBodyText {
    width: 100%;
    height: 100%;
    background-color: transparent;
}

Stylus files support pure CSS, so not being familiar with Stylus is fine.

手写笔文件支持纯CSS，因此不熟悉手写笔就可以了。

If we reload Dillinger now, our styles won't be applied. This is because the app needs to be built first – running the build.js script in the app's folder will compile all the JS and Styl files into compressed JS and CSS files. Run node build in the root of the project, and wait for it to finish. Shouldn't take more than a couple of seconds.

如果现在重新加载Dillinger，我们的样式将不会应用。 这是因为需要首先构建该应用程序–在该应用程序的文件夹中运行build.js脚本会将所有JS和Styl文件编译为压缩的JS和CSS文件。 在项目的根目录中运行node build ，并等待其完成。 不应超过几秒钟。

Reload Dillinger now, and notice everything is just like we want it – except for one thing. The textarea isn't in select-all mode by default. Let's change that. Replace the doneHandler function again, this time with the following:

现在重新加载Dillinger，并注意一切都和我们想要的一样-除了一件事。 默认情况下，textarea不在全选模式下。 让我们改变它。 再次用以下内容替换doneHandler函数：

function _doneHandler(jqXHR, data, response){
            var resp = JSON.parse(response.responseText)
            var textarea = $('#modalBodyText')
            $(textarea).val(resp.data)
            $('#myModal').on('shown.bs.modal', function (e) {
                $(textarea).focus().select()
            }).modal()
        }

First cache the fetched textarea in order to avoid duplicate jQuery selectors. Then, we put the data inside the textarea, as we did before, but before calling Bootstrap's modal() method on the modal window, we define an event listener which triggers when the modal appears (after all CSS transitions). When it's done, we put the focus inside the textarea and force a select-all state with the select() method.

首先缓存获取的文本区域，以避免重复的jQuery选择器。 然后，我们像以前一样将数据放入textarea中，但是在modal()态窗口上调用Bootstrap的modal()方法之前，我们定义了一个事件侦听器，该事件侦听器会在模态出现时触发(在所有CSS转换之后)。 完成后，我们将焦点放在文本区域内，并使用select()方法强制选择全选状态。

If you reload Dillinger now, you'll see that it works and our HTML content is automatically selected. Run node build again to rebuild everything.

如果您现在重新加载Dillinger，您会看到它可以正常工作，并且我们HTML内容被自动选择。 再次运行node build以重新node build所有内容。

结语 (Wrapping up)

While still on your own branch, commit the project with the message "Upgraded ShowHTML function to display HTML content in an auto-focused select-all textarea". A lot of files will have been changed due to the build process, but that's fine. Let's push our branch online now.

仍在自己的分支上时，提交消息“ Upgradeed ShowHTML function以在自动聚焦的全选文本区域中显示HTML内容”。 由于构建过程，很多文件都会被更改，但这很好。 现在让我们的分支机构在线。

git push origin showhtml-fix

Our new branch has now appeared in the repo on GitHub.

我们的新分支现已出现在GitHub的仓库中。

We send a Pull Request by clicking "Compare and Pull Request". After writing a good description, and potentially linking to a related issue as seen in the screenshot below, we click "Send Pull Request".

我们通过单击“比较并请求”发送请求请求。 在写好描述并可能链接到相关问题后，如下面的屏幕快照所示，我们单击“发送请求”。

结论 (Conclusion)

That's it! With the PR sent, all that's left for us to do is wait for the author's feedback. Should our PR be accepted, we need to execute the steps in the "Connecting your repo to the original" section to fetch the latest version into our own repo.

而已！ 发送公关后，剩下要做的就是等待作者的反馈。 如果我们的PR被接受，我们需要执行“将您的存储库连接到原始存储库”部分中的步骤，以将最新版本获取到我们自己的存储库中。

Hopefully you've learned something new following along this contribution process – if you have any suggestions, questions, feedback or requests, please leave them in the comments below.

希望您在此贡献过程中学到了一些新的东西–如果您有任何建议，问题，反馈或要求，请在下面的评论中保留。

翻译自: https://www.sitepoint.com/contributing-open-source-dillinger-case-study/