Skip to content

Latest commit

 

History

History
169 lines (101 loc) · 6.58 KB

GUIDE.md

File metadata and controls

169 lines (101 loc) · 6.58 KB
Raw

目录结构

PROJECT-NAME/
    README.md
    AUTHORS
    LICENSE
    src/
    doc/

README.md

GitHub 支持多种轻量级标记语言(详见github-markup)，可以将纯文本转换成 HTML，README 文件使用 markdown 格式来编写，并保存为 README.md，以便 github 识别。

README.md 文件内容包括项目介绍、如何编译安装、如何使用。

README.md 文件以“项目名 - 项目简介”为标题：

example - a Short Description 
=============================

开源站点将会根据这些信息来生成站点内容：

project name

在标题下面写上项目详细介绍，并列出相关链接：

This is an example project, aim to be a reference of how project source code and document should be organized.

 * Homepage: <http://netease.github.com/projectname>
 * Mailing list: <https://groups.google.com/group/projectname>
 * Documentation: <http://projectname.readthedocs.org>
 * Wiki: <https://github.com/netease/projectname/wiki/>
 * Issues: <https://github.com/netease/projectname/issues/>
 * Tags: java, spring

根据这些信息来生成项目详细介绍和相关链接地址：

project detail

相关链接里面的 Tags 给项目任意打标签，如编写语言和项目的用途，常见的标签有 web、java、c、html5、libary、plugin 等。

README.md 文件和 markdown 格式几个需要注意的地方：

  • 项目简介尽可能用一句话介绍
  • 段落顶格开始，空格是格式定义的一部分
  • 代码段空 4 格
  • README.md 和 AUTHORS 文件用 UTF-8 编码，否则在 github 上无法正常显示
  • README.md 里面的 https://github.com/用户名/ 前缀的链接改成 https://github.com/NetEase/ 前缀
  • 项目名称 - 简介必须定义
  • 项目详细介绍必须定义
  • 相关连接、类别、标签等信息必须定义
  • Tags 必须定义并且为最后一项

更多 markdown 例子查看 markdown 文档源文件和对应的 HTML。

AUTHORS

AUTHORS 文件列出项目的作者及其联系方式：

* Firstname Lastname <[email protected]> <twitter:@foo> <twitter:#foo-list> <weibo:@foo> <github:foo> <linkedin:foo> <http://foo.com>

    Biography about the author, in paragraph format. Hyperlink like http://example.com can be used here.

    Second paragraph.

邮箱地址和主页直接用 <> 包起来，其他 twitter、weibo 等按上面的例子写。紧跟 * 号行下的不以 * 开头的内容视为该用户的简介，最好用一段文字描述，链接等可用markdown的格式编写。站点会展示这些信息：

authors

作者信息将随着项目出现在站点的不同地方，如上面截图中的 Quick Info。

头像用作者的邮箱(如上面的 [email protected])为 ID 从 gravatar 取得，跟 github 的一致。请登陆 http://gravatar.com 用邮箱注册并更改头像。

LICENSE

授权协议内容放在 LICENSE 文件里，建议在文件名后面加上相应的后缀，比如，MIT License 对应的文件名就是 LICENSE.mit，BSD License 对应的文件名就是 LICENSE.bsd，特别的，GPL家族的建议用 COPYING 加上相应后缀当文件名，GPL 的文件名可以是 COPYING.gnu，LGPL 的文件名可以是 COPYING.lib 或 COPYING.lesser，而 AGPL 的文件名可以是 COPYING.affero。

若采用多个授权协议，请在 LICENSE 文件里列出协议名称和协议文件名。协议文件名建议采用 gpl-2.0.txt、mpl-2.0.txt 这样的形式。

src/

如果没有来自语言或者打包工具的约定和要求，源代码建议放在 src/ 目录下。

doc/

建议使用一种文档生成工具来制作文档，并在 release 的时候生成一份 HTML 格式的文档。

发布版本和 Git tag

按照约定，软件发布版本的时候打上 git 标签，如发布 0.1 打 v0.1 标签：

$ git tag v0.1

并推送到 github 上：

$ git push origin --tags

站点会根据 git tag 生成版本信息，详见上面截图中的 Quick Info。

关于 git tag 的详细信息查看 git-tag 或者运行 git help tag。

打包

打包请遵循所使用的语言的惯例。

c autotools

make dist 生成的 release tarball 里带有 configure 和 HTML 格式的文档，允许在另外一个目录里 configure && make && make install ，并能成功安装。

详见 http://sourceware.org/autobook/

样例(源) https://github.com/NetEase/example/tree/master/skel/c/

python distutils

python setup.py install 能安装成功，并能安装到 virtualenv。

详见 http://docs.python.org/distutils/index.html

样例(源) https://github.com/NetEase/example/tree/master/skel/python/

java ant/maven

编写 ant 的 build.xml 或者 maven 的 pom.xml，便于编译整个项目。

详见 http://ant.apache.org/ http://maven.apache.org/

样例(源1 2) https://github.com/NetEase/example/tree/master/skel/java/

关于 Git

推荐读物

Windows 客户端

Linux 客户端

  • Debian/Ubuntu: apt-get install git
  • Fedora/RHEL: yum install git

Mac 客户端