There are many ways to make sure your code respects a given code standard – we’ve covered several before. But enforcing a standard team-wide and making sure everyone knows about mistakes before they’re applied to the project isn’t something that’s very easy to do. Travis and Jenkins can both be configured to do these checks, but aren’t as easygoing about it as the solution we’re about to look at: Nitpick CI.
有很多方法可以确保您的代码遵守给定的代码标准-我们之前已经介绍了几种方法 。 但是,要在整个团队范围内实施标准,并确保每个人在将错误应用到项目之前都知道错误,这并非易事。 可以将Travis和Jenkins都配置为执行这些检查,但是不像我们将要解决的解决方案那样轻松: Nitpick CI 。
![Some Nitpick landing page icons](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/05/1464700380Screenshot-2016-05-31-15.12.16.png)
Nitpick CI is a dead simple single-click tool for making sure submitted Github pull requests adhere to the PSR-2 standard. Unfortunately, Nitpick currently only works with these two specific (but popular) vectors – only Github, and only PSR-2. It’s free for open source projects, so let’s give it a try.
Nitpick CI是一种简单的单击工具,可确保提交的Github拉取请求符合PSR-2标准。 不幸的是,Nitpick目前仅适用于这两个特定(但很流行)的载体-仅Github和PSR-2。 它对开源项目是免费的,因此让我们尝试一下。
自举 (Bootstrapping)
To test Nitpick, we’ll create a brand new repository based on thephpleague/skeleton and pretend we’re building a new PHP package. The skeleton already respects PSR-2, so it’s a perfect candidate for an invalid PR. Feel free to follow along!
为了测试Nitpick,我们将基于phpleague / skeleton创建一个全新的存储库,并假装我们正在构建一个新PHP包。 骨架已经尊重PSR-2,因此它是无效PR的理想选择。 随时跟随!
git clone https://github.com/thephpleague/skeleton nitpick-test
cd nitpick-test
find . -type f -print0 | xargs -0 sed -i 's/:author_name/Bruno Skvorc/g'
find . -type f -print0 | xargs -0 sed -i 's/:author_usernamename/swader/g'
find . -type f -print0 | xargs -0 sed -i 's/:author_website/http:\/\/bitfalls.com/g'
find . -type f -print0 | xargs -0 sed -i 's/:author_email/bruno@skvorc.me/g'
find . -type f -print0 | xargs -0 sed -i 's/:vendor/sitepoint/g'
find . -type f -print0 | xargs -0 sed -i 's/:package_name/nitpick-test/g'
find . -type f -print0 | xargs -0 sed -i 's/:package_description/nitpick-test package for a SitePoint tutorial/g'
rm CONDUCT.md
rm -rf .git
The above commands clone the skeleton, replace placeholder values with real values, and delete some files we don’t need. The project is now ready to be committed and pushed online (as long as you created a repo on Github).
上面的命令克隆骨架,用实值替换占位符值,并删除一些我们不需要的文件。 现在就可以提交该项目并将其推送到网上(只要您在Github上创建了一个仓库即可)。
git init
git remote add origin YOUR_ORIGIN
git add -A
git commit -am "Initial commit"
git push -u origin master
We can now tell Nitpick to track it.
现在,我们可以告诉Nitpick对其进行跟踪。
配置Nitpick (Configuring Nitpick)
To set up Nitpick, we really only have to register for it through Github’s Oauth:
要设置Nitpick,我们实际上只需要通过Github的Oauth进行注册:
![Sign up button](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/05/1464700840Screenshot-2016-05-31-15.20.28.png)
Once authorized to look at an account’s repos, Nitpick will offer a list with a single “Activate” button next to each.
一旦被授权查看帐户的存储库,Nitpick将提供一个列表,每个列表旁边都有一个“激活”按钮。
![Activate buttons next to repo names](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/05/1464702897Screenshot-2016-05-31-15.53.55.png)
There’s even a handy search field for instantly filtering the repos list if you have hundreds. One click on the Activate button, and that’s all it takes. Nitpick is now watching the project for PRs and automatically scanning them. Let’s give it a go!
如果您有数百个,甚至还有一个方便的搜索字段可立即过滤回购清单。 一键单击“激活”按钮,仅此而已。 Nitpick现在正在监视项目中的PR,并自动对其进行扫描。 让我们一起去吧!
非代码公关 (A Non-Code PR)
First, let’s test this on non-code PRs and see how Nitpick will react. We deleted the CONDUCT file in the first steps of this tutorial, but we failed to delete the reference to it from the README file. There’s also a “note” at the top of the README file that needs to be removed.
首先,让我们在非代码PR上进行测试,看看Nitpick将如何React。 在本教程的第一步中,我们删除了CONDUCT文件,但是未能从README文件中删除对该文件的引用。 自述文件顶部还有一个“注释”需要删除。
We can do these changes in the online UI by clicking the edit button on the README file:
我们可以通过单击README文件上的“编辑”按钮在联机UI中进行以下更改:
![Editing the readme file](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/05/1464807581Screenshot-2016-06-01-20.54.43.png)
To actually create an inspectable PR, we tell Github to create a new branch and a new pull request:
为了实际创建可检查的PR,我们告诉Github创建一个新的分支和一个新的请求:
![Creating a pull request from an online edit](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/06/1464807673Screenshot-2016-06-01-21.00.25.png)
As expected, the PR is left untouched – nothing really happens and we can merge it. The file has no code to inspect, so no notifications are issued.
正如预期的那样,PR保持不变–确实没有发生任何事情,我们可以将其合并。 该文件没有要检查的代码,因此不会发出任何通知。
![PR untouched by Nitpick](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/06/1464808123Screenshot-2016-06-01-21.07.33.png)
有效的代码提取请求 (A Valid Code Pull Request)
Now, let’s add a change to the sample controller. The change should be minimal, just to see if Nitpick will do anything. For simplicity, we can use the web UI again.
现在,让我们对示例控制器进行更改。 所做的更改应该很小,以查看Nitpick是否会做任何事情。 为简单起见,我们可以再次使用Web UI。
We can change the content of src/SkeletonClass.php
to:
我们可以将src/SkeletonClass.php
的内容更改为:
< ?php
namespace League\Skeleton;
class SkeletonClass
{
/**
* Create a new Skeleton Instance
*/
public function __construct()
{
// constructor body
}
/**
* Friendly welcome
*
* @param string $phrase Phrase to return
*
* @return string Returns the phrase passed in
*/
public function echoPhrase($phrase)
{
$phrase .= "- and here is a suffix!!";
return $phrase;
}
}
And again, nothing happens. Is Nitpick even working?
再说一次,什么也没有发生。 Nitpick还在工作吗?
![Nitpick not showing signs of life on the pull request - it's left untouched as if Nitpick wasn't in the equation at all](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/06/1464808462Screenshot-2016-06-01-21.12.38.png)
无效的代码提取请求 (An Invalid Code Pull Request)
Now, let’s write some PSR-2 unfriendly code on purpose. PSR-2 states:
现在,让我们故意编写一些PSR-2不友好的代码。 PSR-2指出:
There MUST NOT be a hard limit on line length; the soft limit MUST be 120 characters; lines SHOULD be 80 characters or less.
线长绝不能有硬性限制; 软限制必须为120个字符; 每行不得超过80个字符。
and
和
Visibility MUST be declared on all properties and methods; abstract and final MUST be declared before the visibility; static MUST be declared after the visibility.
必须在所有属性和方法上声明可见性; 摘要和最终内容必须在可见性之前声明; 静态必须在可见性之后声明。
While there are many more rules, these seem easy enough to break. Let’s change the contents of src/SkeletonClass.php
to:
尽管还有更多规则 ,但似乎很容易打破。 让我们将src/SkeletonClass.php
的内容更改为:
<?php
namespace League\Skeleton;
class SkeletonClass
{
$someProp = "foo";
public $someOtherProp = "bar";
/**
* Create a new Skeleton Instance
*/
public function __construct()
{
// constructor body
}
public final function thisIsNotPsr2() { echo "Hello!"; }
/**
* Friendly welcome
*
* @param string $phrase Phrase to return
*
* @return string Returns the phrase passed in
*/
public function echoPhrase($phrase)
{
$phrase .= "- and here is a suffix!! But it doesn't end there - we have here a very, very long line that's actually a bunch of text. Technically, it should be broken up or something I guess.";
return $phrase;
}
}
We’ve added two properties, of which only one is defined according to rules. The other is missing its visibility declaration. Furthermore, we added a technically valid but standards-invalid method which defines its finality after the visibility, and then has its entire body in the same line as the method’s declaration. Lastly, we extended the previously added suffix to an extreme length.
我们添加了两个属性,其中只有一个是根据规则定义的。 另一个缺少其可见性声明。 此外,我们添加了一种技术上有效但标准无效的方法,该方法在可见性之后定义其终结性,然后将其整个主体与该方法的声明放在同一行中。 最后,我们将之前添加的后缀扩展到了极限。
Once we submit the PR, we can see things are a bit different:
提交PR后,我们可以看到情况有所不同:
![Nitpick inspection alerts](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/06/1464809631Screenshot-2016-06-01-21.33.30.png)
Nitpick displays the mistakes inline, specifically pointing out what’s wrong – whether it’s just one offense or multiple ones as in the case of our added method.
Nitpick内联显示错误,特别指出出了什么问题–在我们所添加的方法中,只是一个罪行还是多个罪行。
Due to Nitpick commenting on the PR directly as if a user were doing it, notifications are also sent via email, so it’s nearly impossible to miss them:
由于Nitpick就像用户在进行PR一样直接在PR上进行评论,因此通知也通过电子邮件发送,因此几乎不可能错过它们:
![Nitpick CI notification in email](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/06/1464809970Screenshot-2016-06-01-21.39.15.png)
One thing it missed, however, is the line length. It didn’t react to it at all. This is because under the hood, Nitpick uses PHP CodeSniffer and it’s PSR-2 preset, and what ever PHPCS considers valid, Nitpick agrees with. On the specific line length issue, PHPCS considers it merely a warning, which we can see if we run it manually on our code:
但是,它错过的一件事是线长。 它根本没有React。 这是因为在幕后,Nitpick使用PHP CodeSniffer及其PSR-2预设,并且Nitpick同意任何PHPCS认为有效的内容。 在特定的行长问题上,PHPCS认为它只是一个警告,我们可以看看是否在代码上手动运行它:
composer global require squizlabs/php_codesniffer
~/.config/composer/vendor/bin/phpcs --standard=PSR2 src/SkeletonClass.php
![PHPCS flagging line length as a warning only](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/06/1464813026Screenshot-2016-06-01-22.30.11.png)
After inspection, it’s not like Nitpick will block the merge attempt. We can still go ahead and merge the PR as usual. The inspection messages, however, are there to stay for public record until we get them fixed. Let’s do that now. On the command line, we’ll clone that PR’s branch:
经过检查后,Nitpick不会阻止合并尝试。 我们仍然可以像往常一样合并PR。 但是,检查消息将保留在公共记录中,直到我们修复它们为止。 现在开始吧。 在命令行上,我们将克隆该PR的分支:
git fetch origin
git checkout -b Swader-patch-3 origin/Swader-patch-3
We then make the required edits, changing the SkeletonClass.php
‘s contents to:
然后,我们进行必要的编辑,将SkeletonClass.php
的内容更改为:
<?php
namespace League\Skeleton;
class SkeletonClass
{
public $someProp = "foo";
public $someOtherProp = "bar";
/**
* Create a new Skeleton Instance
*/
public function __construct()
{
// constructor body
}
final public function thisIsNotPsr2()
{
echo "Hello!";
}
/**
* Friendly welcome
*
* @param string $phrase Phrase to return
*
* @return string Returns the phrase passed in
*/
public function echoPhrase($phrase)
{
$phrase .= "- and here is a suffix!! But it doesn't end there - we have here a very, very long line that's actually a bunch of text. Technically, it should be broken up or something I guess.";
return $phrase;
}
}
After committing and pushing with:
提交并推送后:
git add -A
git commit -m "Fixed nitpicks"
git push origin Swader-patch-3
… the only feedback we get about having fixed the mistakes is the fact that Nitpick’s previous comments on the PR are now outdated:
…我们得到的有关纠正错误的唯一反馈是,事实是Nitpick先前对PR的评论已过时:
![Nitpick comments are outdated](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2016/06/1464811890Screenshot-2016-06-01-22.11.12.png)
Our PR is now ready to be merged!
我们的PR现在可以合并了!
结论 (Conclusion)
While Nitpick is, admittedly, very specific in its use case, it’s also very good at it – it does one thing, and does it well. A single click is all it takes to configure it, and the entire team benefits from advanced standard inspections which can now be left out of other CI tools like Jenkins and Travis, instead letting them focus on actual tests. Being free for open source and incredibly easy to set up, there’s truly no reason not to give it a go.
诚然,尽管Nitpick在用例上非常具体,但它也非常擅长–它做一件事,并且做得很好。 只需单击一下即可配置,整个团队都受益于高级标准检查,这些检查现在可以从Jenkins和Travis等其他CI工具中省去,而让他们专注于实际测试。 由于免费提供开源软件,并且易于设置,因此没有理由不去尝试。
Granted, there are some nitpicks with Nitpick:
当然,还有一些Nitpick的挑逗:
- due to Nitpick using PHPCS under the hood, we’re constrained by what the tool can do. Not only that, we’re also constrained by the tool’s interpretation of the PSR-2 rules. There’s no way to customize the ruleset, or to define a different implementation of the standard (for now). 由于Nitpick在后台使用PHPCS,因此该工具的功能受到了限制。 不仅如此,我们还受到该工具对PSR-2规则的解释的限制。 目前尚无法自定义规则集或定义标准的其他实现。
- when mistakes get introduced, there’s no blocking indicator in the PR. CI tools like Travis and Scrutinizer do this really well in that they work together and use the PR’s readiness indicator to mark a build fail or pass. While code standards have no real effect on a build’s technical realization passing or failing, it’d be nice to have some more visual feedback in the spirit of those tools. 当引入错误时,PR中没有阻止指示器。 像Travis和Scrutinizer这样的CI工具可以很好地做到这一点,因为它们可以协同工作,并使用PR的就绪指示器来标记构建失败或通过。 尽管代码标准对构建的技术实现的成功或失败没有真正的影响,但最好能根据这些工具的精神提供一些直观的反馈。
when mistakes get fixed, there’s no clear indication of the issues having been rectified. I like Scrutinizer‘s approach there – clear indications in the PR, and an email saying some issues were fixed. This gets sent to the entire team, so everyone’s immediately on the same page.
当错误得到解决时,没有明确的迹象表明问题已得到纠正。 我喜欢那里的Scrutinizer的方法-PR中有明确的指示,还有一封电子邮件中指出一些问题已解决。 这将发送给整个团队,因此每个人都将立即进入同一页面。
That said, I’ll definitely activate Nitpick on all my open source projects – there’s just no reason not to. As a heavy PSR-2 user, I can leave the standards checking to Nitpick and forget all about it in tools like Travis and Scrutinizer, instead letting those tools focus on what matters – code inspection and tests.
就是说,我一定会在所有开放源代码项目中激活Nitpick –没有理由不这样做。 作为沉重的PSR-2用户,我可以将标准检查留给Nitpick,而不必在Travis和Scrutinizer等工具中将其全部遗忘,而让这些工具专注于重要的事情-代码检查和测试。
What do you use for code inspection? Do you rely on external tools, or local tools only? Maybe both? Let us know!
您使用什么进行代码检查? 您是依靠外部工具还是仅依靠本地工具? 也许两者都有? 让我们知道!
翻译自: https://www.sitepoint.com/nitpicking-over-code-standards-with-nitpick-ci/