新手如何写一个好的项目描述文件

新手如何写一个项目的README.md

想写好一个README文件首先需要熟悉MarkDown语法,再次就不过多讲解了。

主要分为几个大的结构就像写简历一样123罗列出来即可;
1.项目概况
2.技术栈
3.项目结构
4.开发环境及依赖
5.友情提示
6.代码规范
7.项目规范

上例子

贝程教育-学员笔记助手

学员笔记助手前端项目说明文档,本文档旨在让参与项目人员了解项目结构, 项目依赖, 业务模块, 组件说明, git flow …

技术栈

vue2 vuex vue-router vue-form node koa koa-router webpack scss

项目结构

.
├── build // 构建脚本 webpack, devServer...
├── config // 配置 env, port, host, assetsPath...
├── node_modules // 依赖的第三方包
├── src // 源代码
│   └── client
│       ├── components // 前端通用组件
│       ├── containers // 路由匹配的各页面组件
│       ├── helpers // 功能函数
│       ├── images // 图片资源、
│       ├── routes // 路由配置
│       ├── service // 接口请求函数
│       ├── styles // 样式
│       ├── vuex // 全局 stote. 含有各模块的 action, mutation, getter, state...
│       └── main.js 项目入口文件
├── dist // 源代码编译后的生成线上环境代码
├── .babelrc // babel 配置
├── .editorconfig // 编辑器 code format 配置
├── .eslintrc.js // eslint 配置
├── .gitignore // 不纳入 git 版本控制的 /文件夹?/ 列表
├── package.json // 项目信息文件
└── README.md // 说明
.

开发环境依赖

推荐工具

编辑器插件 (无论使用什么IDE,下面列表中 * 开头的插件必装, 以下插件皆为 VS Code 中插件)

  • *ESLint
  • *EditorConfig
  • Vetur
  • vue
  • Babel
  • Path Intellisense

让 VS Code 的 ESLint 插件支持 .vue 文件

打开 VS Code
打开用户设置 windows: 文件 > 首选项 > 设置
打开用户设置 mac: Code > 首选项 > 设置
在 user setting.json 添加下面的代码

"eslint.validate": [
    "javascript",
    "javascriptreact",
    "html",
    "vue"
]

代码规范 (重要)

!!!本项目遵从 airbnb js 规范, 并将检测集成进 webpack , 所以不符合规范代码无法编译成功。
可以使用编辑器插件自动检测代码规范, 如上方 VS Code 的 ESLint 插件, 其他编辑器自行 google

通用组件

SVG 图标 页面

执行以下命令会使用默认浏览器打开 svg 图标页面, 项目中使用的图标尽收于此,单击图标复制代码,组件中引入 SvgIcon 直接粘贴复制的图标代码便可使用

$ npm run openSvg

run & build

# cd 到项目目录
$ cd workspace/wechat-restaurant
# 安装依赖
$ npm install
# 启动开发环境
$ npm run start

git flow

分支

  • master // 主干
  • dev // 开发主干
  • release // 测试分支
  • feature // 功能分支
  • fixbug // bug 修复分支

工作流

项目人员开发时由 dev 分支创建新的 feature 分支,分支命名规则为对应的任务名字
开发完成后, 向 leader 发起 pull request, code review 完毕合并入 dev 分支
提测时从 dev 分支拉出 release, bug 由 release 分支拉出 fixbug 修复, 修复后发起 pull request, code review 后合并入 release 与 dev

以上请复制到README.md中预览效果,不喜勿喷!

作者:贝程教育
链接:https://www.jianshu.com/p/11fca4b2b27f
来源:简书
简书著作权归作者所有,任何形式的转载都请联系作者获得授权并注明出处。

  • 0
    点赞
  • 7
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
对于GitHub的新手教程,我可以为你提供一些基本步骤和建议: 1. 注册一个GitHub账号:在GitHub官方网站上注册一个账号。填所需的信息并验证您的电子邮件地址。 2. 创建一个新存储库(Repository):登录GitHub后,在主页右上角点击“New”按钮,然后选择“New Repository”创建一个新的存储库。 3. 命名您的存储库:给您的存储库起一个有意义的名称,并选择是否将其设为公共或私有。 4. 初始化您的存储库:选择初始化选项,您可以选择从头开始创建新的文件,或者将现有代码导入到存储库中。 5. 学习Git基本操作:Git是一种版本控制系统,用于管理和跟踪文件更改。学习常用的Git命令,如git clone、git add、git commit和git push等。 6. 创建分支(Branch):分支是用于在代码开发过程中进行不同功能或修复的分离工作区。学习如何创建和切换分支,并在不同分支上进行工作。 7. 提交更改:在您的本地存储库中进行更改后,使用git命令提交更改。并且使用有意义的提交消息来描述每个更改。 8. 发起合并请求(Pull Request):如果您想将您的更改合并到主分支(通常是master分支),可以发起合并请求。其他人可以审查您的更改并提供反馈。 9. 探索GitHub社区:GitHub是一个开源社区,您可以发现各种有趣的项目和贡献者。浏览一些项目,学习他人的开发方式,并积极参与讨论和贡献。 这些是GitHub的一些基本步骤和建议,希望对您有所帮助。您还可以查阅GitHub的官方文档和其他在线教程来深入学习。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值