diff --git a/README-zh.md b/README-zh.md index 900100f..8ab6e28 100644 --- a/README-zh.md +++ b/README-zh.md @@ -1,7 +1,9 @@ -[](http://wearehive.co.uk/) +[EN](./README.md) +[](http://wearehive.co.uk/) + # 项目规范 · [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) javascript工程项目的一系列最佳实践策略 @@ -29,6 +31,9 @@ javascript工程项目的一系列最佳实践策略 ## 1. Git + +![git](/images/branching.png) + ### 1.1 一些Git规则 有一套规则要牢记： @@ -165,6 +170,9 @@ javascript工程项目的一系列最佳实践策略 ## 2. 文档 + +![文档](/images/documentation.png) + * 使用这个 [模板](./README.sample.md) 给 `README.md`, 欢迎添加里面没有的内容。 * 对于具有多个存储库的项目，请在各自的`README.md`文件中提供它们的链接。 * 随项目持续的更新 `README.md`. @@ -174,8 +182,9 @@ javascript工程项目的一系列最佳实践策略 * 也不要把那些清晰的代码作为不写注释的借口。 * 当代码更新，也请确保注释的同步更新。 - + ## 3. 环境 +![环境](/images/laptop.png) * 如果需要，请分别定义 `development`, `test` 和 `production` 三个环境. _为什么:_ @@ -243,6 +252,9 @@ javascript工程项目的一系列最佳实践策略 ## 4. 依赖 + +![依赖](/images/modules.png) + * 持续跟踪你当前的可用依赖包: e.g., `npm ls --depth=0`. [更多请阅读...](https://docs.npmjs.com/cli/ls) * 查看这些软件包是否已经变得不可用或者已经废弃: `depcheck`. [更多请阅读...](https://www.npmjs.com/package/depcheck) @@ -270,6 +282,8 @@ javascript工程项目的一系列最佳实践策略 ## 5. 测试 +![测试](/images/testing.png) + * 如果需要，构建一个 `test` 环境. _为什么:_ @@ -311,6 +325,9 @@ javascript工程项目的一系列最佳实践策略 ## 6. 结构布局与命名 + +![结构布局与命名](/images/folder-tree.png) + * 围绕产品功能/页面/组件来组织您的文件，而不是围绕角色来组织文件。此外，请将测试文件放在他们对应实现的旁边。 @@ -378,6 +395,9 @@ javascript工程项目的一系列最佳实践策略 ## 7. 代码风格 + +![代码风格](/images/code-style.png) + * 对新项目请使用Stage2和更高版本的JavaScript（现代化）语法。对于老项目，保持与老的语法一致，除非您打算把老的项目也更新为现代化风格。 _为什么:_ @@ -438,6 +458,9 @@ javascript工程项目的一系列最佳实践策略 ## 8. 日志 + +![日志](/images/logging.png) + * 避免在生产环境中使用客户端的日志 _为什么:_ @@ -452,6 +475,9 @@ javascript工程项目的一系列最佳实践策略 ## 9. API + +![API](/images/api.png) + ### 9.1 API 设计 @@ -712,6 +738,9 @@ _为什么:_ ## 10. 证书 + +![证书](/images/licensing.png) + 确保使用您有权使用的这些资源。如果您使用其中的软件库，请记住先查询MIT，Apache或BSD，但如果您打算修改它们，请查看许可证详细信息。图像和视频的版权可能会导致法律问题。 diff --git a/README.md b/README.md index c2eb4c9..7dc57be 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [中文版](./README-zh.md) -[](http://wearehive.co.uk/) +[](http://wearehive.co.uk/) # Project Guidelines · [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) @@ -29,7 +29,9 @@ If you want to share a best practice, or think one of these guidelines should be ## 1. Git +![Git](/images/branching.png) + ### 1.1 Some Git rules There are a set of rules to keep in mind: * Perform work in a feature branch. @@ -165,6 +167,9 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 2. Documentation + +![Documentation](/images/documentation.png) + * Use this [template](./README.sample.md) for `README.md`, Feel free to add uncovered sections. * For projects with more than one repository, provide links to them in their respective `README.md` files. * Keep `README.md` updated as a project evolves. @@ -176,6 +181,9 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 3. Environments + +![Environments](/images/laptop.png) + * Define separate `development`, `test` and `production` environments if needed. _Why:_ @@ -243,6 +251,9 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 4. Dependencies + +![Github](/images/modules.png) + * Keep track of your currently available packages: e.g., `npm ls --depth=0`. [read more...](https://docs.npmjs.com/cli/ls) * See if any of your packages have become unused or irrelevant: `depcheck`. [read more...](https://www.npmjs.com/package/depcheck) @@ -270,7 +281,7 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 5. Testing - +![Testing](/images/testing.png) * Have a `test` mode environment if needed. _Why:_ @@ -312,6 +323,7 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 6. Structure and Naming +![Structure and Naming](/images/folder-tree.png) * Organize your files around product features / pages / components, not roles. Also, place your test files next to their implementation. @@ -378,6 +390,9 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 7. Code style + +![Code style](/images/code-style.png) + * Use stage-2 and higher JavaScript (modern) syntax for new projects. For old project stay consistent with existing syntax unless you intend to modernise the project. _Why:_ @@ -438,6 +453,9 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 8. Logging + +![Logging](/images/logging.png) + * Avoid client-side console logs in production _Why:_ @@ -453,6 +471,9 @@ Having a good guideline for creating commits and sticking to it makes working wi ## 9. API + +![API](/images/api.png) + ### 9.1 API design _Why:_ @@ -709,6 +730,8 @@ For each endpoint explain: ## 10. Licensing +![Licensing](/images/Licensing.png) + Make sure you use resources that you have the rights to use. If you use libraries, remember to look for MIT, Apache or BSD but if you modify them, then take a look into license details. Copyrighted images and videos may cause legal problems. @@ -722,3 +745,5 @@ Sources: [Apigee](https://apigee.com/about/blog), [Wishtack](https://blog.wishtack.com) +Icons by [icons8](https://icons8.com/) + diff --git a/images/api.png b/images/api.png new file mode 100644 index 0000000..2b668d9 Binary files /dev/null and b/images/api.png differ diff --git a/images/branching.png b/images/branching.png new file mode 100644 index 0000000..524e889 Binary files /dev/null and b/images/branching.png differ diff --git a/images/code-style.png b/images/code-style.png new file mode 100644 index 0000000..dc1eae5 Binary files /dev/null and b/images/code-style.png differ diff --git a/images/documentation.png b/images/documentation.png new file mode 100644 index 0000000..195599e Binary files /dev/null and b/images/documentation.png differ diff --git a/images/folder-tree.png b/images/folder-tree.png new file mode 100644 index 0000000..fc90b3c Binary files /dev/null and b/images/folder-tree.png differ diff --git a/images/git.png b/images/git.png new file mode 100644 index 0000000..b5bef7c Binary files /dev/null and b/images/git.png differ diff --git a/images/github.png b/images/github.png new file mode 100644 index 0000000..64b996e Binary files /dev/null and b/images/github.png differ diff --git a/images/hive-red-logo.png b/images/hive-red-logo.png new file mode 100644 index 0000000..10aa6b2 Binary files /dev/null and b/images/hive-red-logo.png differ diff --git a/images/laptop.png b/images/laptop.png new file mode 100644 index 0000000..7bf3f61 Binary files /dev/null and b/images/laptop.png differ diff --git a/images/licensing.png b/images/licensing.png new file mode 100644 index 0000000..6b560e4 Binary files /dev/null and b/images/licensing.png differ diff --git a/images/logging.png b/images/logging.png new file mode 100644 index 0000000..fd9211d Binary files /dev/null and b/images/logging.png differ diff --git a/images/logo.png b/images/logo.png deleted file mode 100644 index 4722173..0000000 Binary files a/images/logo.png and /dev/null differ diff --git a/images/modules.png b/images/modules.png new file mode 100644 index 0000000..0fbe9f8 Binary files /dev/null and b/images/modules.png differ diff --git a/images/testing.png b/images/testing.png new file mode 100644 index 0000000..5f83522 Binary files /dev/null and b/images/testing.png differ