发布一个 GitHub 仓库时需要注意的东西

2017/04/02 Tools

本文全部源于我个人总结,绝对不保证权威性,反正我自己做到不坑你们,你们信不信就是你们的事了。另外,我自己是做到了遵守这些准则的。

GitHub 对我来说是在自己没有工作的时候应该好好整出一个优秀的账号的网站,据说对以后找工作啥的有帮助。所以开仓库就一定要注意了,最近我看到很多人开仓库开的很暴力,而且在很早之前我就想过要写篇博客讲这个了,今天才填坑真是对不起。

请大家期待我即将出的国内使用 Gradle 的正确姿势的教程,会有文字博客和视频教程。绝对天地良心,保证不坑,随后还会附带 Travis CI 的部署教程,也绝对保证不坑。

毕竟,教程要是坑,怎能带你入坑?

什么是暴力开仓库

就是开很糟糕的仓库,放在开源界会被鄙视的项目。

这里排除 IntelliJ-Community 这种比较特殊的仓库,因为人家第一不怕网速慢,第二人家把包都放在仓库里面,免得各种版本不对,这是针对公司的做法 (比如你自己公司也用 Git ,那么这么做是无可厚非的,但是个人项目最好注意一下)。

这也是构建工具出现的原因——由于老是有库,版本还老是换,导致仓库太大了。

注意点

首先,一个稍微正常点的 Git 仓库都一定要注意的东西有:

  • 不要上传目标文件,除非你以非程序员为目标用户
  • 不要上传与仓库本身无关的文件(你需要 gitignore )
  • 尽可能有 LICENSE 和 README

为什么不要上传目标文件

先说一句,目标文件包含 Code Generator 生成的代码,比如 Lex 和 Yacc 生成的 Lexer 和 Parser。

什么意思呢?举个例子,我有一个 Java 的仓库, 然后我把所有编译生成的*.class 文件全部上传(注意是编译生成的,如果你有手写的字节码当我没说),这就很智障了。 你当用户是傻的啊。。。

  1. 如果是想 review 你的代码,不需要看也无法看*.class 的内容
  2. 大量的*.class 以及每次编译都导致的更新(因为你编译一次,对应的*.class 也会变)会让仓库变得巨大(因为 Git 等同对待二进制文件),每次 push 都会很慢
  3. 如果是想 clone 你的仓库,看见那巨大的仓库体积一般人都会知难而退
  4. 几乎每次增量编译都会影响到 Git 监控,虽然目前我没遇到过不过这一定会导致后期 git gc 和 git commit 很慢

这已经是十分充分的理由了。所以, JVM 程序员把*.class ,*.apk 和*.jar 加入 gitignore 吧; Rust 程序员把 Cargo.lock 和*.exe 之类的加入 gitignore 吧; Gradle 用户把 build 目录和.gradle 目录加入 gitignore 吧。

一般情况下,目标文件是放在 GitHub 的 release 界面的。 比如我之前看到过一个 E 站客户端,就是在 release 界面放了个 apk。毕竟这种东西有时体积不能控制,但你又要面向不方便自己构建的人使用,那就在 release 里面放目标文件吧。

与仓库本身无关的文件

我觉得这没什么难理解的。

比如:

  • 我写了一个音乐播放器,我上传了我拿来测试的一堆 wav/ape/flac 文件。
  • 我写了一个压缩工具,然后把我拿来测试的 100 多 mb 的文件上传上去了。
  • 我上传了.idea/workspace.xml
  • 我上传了测试用的.db 文件

这都是不好的,而且为什么不好,我觉得用屁股想都想得到。

如果确实有这个需求怎么办呢?

举个例子,我要部署我的项目到某个 CI (持续集成)上去,然而我的项目用到了 JNI , 原本两部分( CMake 和 Gradle )是我手动分别编译,而且考虑到 CMake 设置编译器等各种猥琐流程, 考虑种种因素,我觉得最好的 Solution 是把 JNI 的 dll/so/jnilib 分别上传到 Git 远端仓库,这样就只需要让 CI 自动构建 Gradle 的部分就好了(因为 CI 涉及测试的自动化)。

事实上我已经成功地把 JNI 项目的构建部署到了 CI ,详见 algo4j

临时解决方案

我有一个替代解决方案。考虑到国内 Git 仓库,比如 Coding.net 和 OSC 的 clone 速度是相当之快的(我学校机房里的批网速(打开我的 GitHub 平均需要五秒)都能达到 10mb/s 的 clone 速度)。

这时我们就可以先在国内 Git 源开个仓库用来堆这种破玩意,然后使用 Git 的 submodule 来解决( submodule 怎么用,自己股沟)。

关于 IntelliJ 的 workspace.xml

比较了解 IntelliJ 系的 IDE 的同学应该注意到过,.idea 目录下有很多各种各样的配置,其中有一个巨大的 workspace.xml ,它的大小飘忽不定,不过一般在 20kb 到 70kb 之间。

这其实是 IntelliJ 的一个对你编辑状态的缓存,比如你复制粘贴了什么东西, 你剪切了什么东西,你光标怎么移动了一下,你 Git commit 时写了什么 commit message , IntelliJ 都会把这些存进去。

而且编辑时,这破玩意是会大大改变的,有时你代码都没动,它变了,你 commit 的时候就会无意中把这些 commit 进去,造成 commit log 和整个仓库的污染。

看完上面这段,你还会上传 workspace.xml 吗? :joy:

尽可能有 LICENSE 和 README

重要性我就不说了, LICENSE 你懂得,这里推荐最邪恶的 GPLv3.0 ,最不推荐 MIT。协议怎么选,网上很多教程,我就不赘述了。

MIT 一时爽,抄袭火葬场。

README 尽可能使用人性化的语言写,尽可能用英文写,里面一般包含:

  • 尽可能简洁的简介
  • 特色,吸引别人
  • 如果是软件类,放截图,可以考虑录制 GIF
  • Wiki 的链接
  • LICENSE
  • 装逼用的 badge ,比如 CI ,比如 Gitter ,比如 CodeCov ,比如 CodeClimate
  • clone、build 说明
  • 维护指北等各种指北的链接
  • release 的 binary 的下载链接
  • 如果是库性质的,放构建工具远端仓库地址(比如 JitPack ,或者你牛逼,你上 Maven Central )
  • Contributors

于是我就暂时介绍到这里,有什么欢迎发邮件通知我补充。


Search

    Post Directory



    如果觉得这篇文章给您带来了收获或者说它值得您这么做,您可以选择对我进行捐助。
    下面是微信支付哟