docs: contributing guides

CONTRIBUTING.md

@@ -1,45 +1,48 @@
 # Contributing Guides
 
-## How to get started
+Welcome, and thank you for your interest in contributing to Leoric!
 
-Three steps:
+There are many ways in which you can contribute, beyond writing code. The goal of this document is to provide a bird's-eye overview of how you can get involved.
 
-1. Install databases we intend to support, namely MySQL, PostgreSQL, and SQLite
-2. Install `node_modules` (which might take long)
-3. Happy hacking
+## Reporting Issues
 
-### Preparing environment
+Have you identified a reproducible problem? Have a feature request? We want to hear about it! Here's how you can make reporting your issue as effective as possible.
 
-```bash
-$ brew install mysql postgres sqlite
-$ brew service start mysql
-$ brew service start postgres
-```
+### Look For an Existing Issue
 
-### Running tests
+If you find your issue already exists, make relevant comments and add your reaction. Use a reaction in place of a "+1" comment:
 
-```bash
-$ npm install
-# run all the tests in test/unit directory
-$ npm test unit
-# run all the tests in test/integration directory
-$ npm test integration
-# skip pretest task
-$ npm run test-local
-```
+- 👍 - upvote
+- 👎 - downvote
 
-To be more specific, we can filter test files and cases:
+If no such issue were found, create a new issue using the guidelines below.
 
-```bash
-$ npm run test-local -- test/unit/test.connect.js --grep "should work"
-```
+### Writing Good Bug Reports and Features Requests
 
-It is recommended that we start with unit tests first, such as:
+Please include the following with each issue:
 
-```bash
-$ npm run test-local -- test/unit/adapters/test.sequelize.js
-```
+- Version of Leoric
+- Version of your database
+- Version of your node
+- Your operating system
+- Reproducible steps (1... 2... 3...) that cause the issue
+- What was expected, versus what you actually get
+- A code snippet that demonstractes the issue or a link to a code repository the developers can pull down to recreate the issue locally
 
-## How the code is organized
+### Final Checklist
 
-TODO
+Please remember to do the following:
+
+- [ ] Search the issue repository to ensure your report isn't duplicated
+- [ ] Describe the environment that runs leoric, database, Node.js, etc.
+- [ ] Simplify your code around the issue to better isolate the problem
+
+Don't feel bad if the developers can't reproduce the issue right away. They will simply ask for more information!
+
+## Contributing Fixes
+
+If you are interested in writing code to fix issues, please see [How to Contribute](https://www.cyj.me/leoric/contributing/guides) in the documentations.
+
+# Thank You!
+
+Your contributions to open source, large or small, make this project possible. Thank you for taking the time to contribute.

CONTRIBUTING.zh-CN.md

@@ -0,0 +1,48 @@
+# 如何参与
+
+欢迎阅读本文，感谢你有兴趣参与 Leoric！
+
+即便不写代码，参与项目的方式也有很多种。本文的目标就是提供一些有关如何参与项目的概要介绍。
+
+## 提交问题反馈
+
+只要你遇到稳定复现问题，或者想要提个需求，我们对此都表示欢迎！参考下文以尽可能有效地提交问题反馈。
+
+### 查找是否已知问题
+
+在提问题反馈之前，请确保问题是否已经被提交过。如果是已知问题，可以在相关问题下面留言或者反馈。推荐使用 Github 的表请回复来替代无意义的 +1 评论：
+
+- 👍 - 赞同
+- 👎 - 反对
+
+如果没有找到相关问题，按照如下指引提交繁体反馈
+
+### 编写良好的问题反馈和功能需求
+
+请在你的问题反馈中包含如下信息：
+
+- Leoric 版本
+- 所使用的数据库
+- 所使用的 Node.js
+- 所使用的操作系统
+- 稳定复现问题的步骤描述
+- 期望获得的结果，实际取得的结果
+- 一段能够演示问题的代码片段，或者一个能够让 Leoric 开发者访问并在本地复现问题的代码仓库
+
+### 提交前检查
+
+请在提交问题反馈前检查如下事项：
+
+- [ ] 检索当前仓库的问题反馈列表，确保想要提交的问题不是已知问题
+- [ ] 提供相关使用信息，比如 Leoric 版本、数据库、Node.js、操作系统信息等
+- [ ] 尽可能简化你的代码示例，降低复现问题的成本
+
+如果开发者没能复现你的问题，也不要沮丧。我们会向你进一步了解相关信息。
+
+## 贡献代码
+
+如果你有兴趣帮助解决问题反馈，参考 Leoric 文档中的 [如何贡献代码](https://www.cyj.me/leoric/zh/contributing/guides) 一文。
+
+# 谢谢你！
+
+无论大还是小，你对开源工作的关注或者贡献都对此项目意义重大。感谢你为此投入时间。

Readme.md

@@ -5,7 +5,7 @@
 [![Build Status](https://travis-ci.org/cyjake/leoric.svg)](https://travis-ci.org/cyjake/leoric)
 [![Coverage Status](https://coveralls.io/repos/github/cyjake/leoric/badge.svg?branch=master)](https://coveralls.io/github/cyjake/leoric?branch=master)
 
-Leoric is an object-relational mapping for Node.js, which is heavily influenced by Active Record of Ruby on Rails. See the [documentation](http://cyj.me/leoric) for detail.
+Leoric is an object-relational mapping for Node.js, which is heavily influenced by Active Record of Ruby on Rails. See the [documentation](https://www.cyj.me/leoric) for detail.
 
 ## Usage
 
@@ -71,4 +71,23 @@ await realm.sync();
 | `Post.update({ id: 42 }, { title: 'Skeleton King' })` | `UPDATE posts SET title = 'Skeleton King' WHERE id = 42` |
 | `Post.remove({ id: 42 })`               | `DELETE FROM posts WHERE id = 42`                  |
 
-A more detailed syntax table may be found at the [documentation](http://cyj.me/leoric/#syntax-table) site.
+A more detailed syntax table may be found at the [documentation](https://www.cyj.me/leoric/#syntax-table) site.
+
+## Contributing
+
+There are many ways in which you can participate in the project, for example:
+
+- [Submit bugs and feature requests](https://github.com/cyjake/leoric/issues), and help us verify as they are checked in
+- [Review source code changes](https://github.com/cyjake/leoric/pulls)
+- Review the [documentation](https://www.cyj.me/leoric) and make pull requests for anything from typo to new content
+
+If you are interested in fixing issues and contributing directly to the code base, please see the document [How to Contribute](https://www.cyj.me/leoric/contributing/guides), which covers the following:
+
+- The development workflow, including debugging and running tests
+- Coding guidelines
+- Submitting pull requests
+- Contributing to translations
+
+## Related Projects
+
+If developing web applications with [egg framework](https://eggjs.org/), it's highly recommended using the [egg-orm](https://github.com/eggjs/egg-orm) plugin.

docs/basics.md

@@ -192,7 +192,7 @@ await connect({
 await connect({ ...opts, path: '/path/to/models' });
 ```
 
-If developing web applications with Egg framework, it's highly recommended using [egg-orm](https://github.com/eggjs/egg-orm) plugin.
+If developing web applications with Egg framework, it's highly recommended using the [egg-orm](https://github.com/eggjs/egg-orm) plugin.
 
 ## Reading and Writing Data
 

docs/contributing/guides.md

@@ -0,0 +1,98 @@
+---
+layout: en
+title: How to Contribute
+---
+
+## Get Started
+
+Three steps:
+
+1. Install databases we intend to support, namely MySQL, PostgreSQL, and SQLite
+2. Install `node_modules` (which might take long)
+3. Happy hacking
+
+### Preparing Environment
+
+```bash
+$ brew install mysql postgres sqlite
+$ brew service start mysql
+$ brew service start postgres
+```
+
+### Running Tests
+
+```bash
+$ npm install
+# run unit tests
+$ npm test unit
+# run integration tests
+$ npm test integration
+```
+
+To be more specific, we can filter test files and cases:
+
+```bash
+$ npm run test -- test/unit/test.connect.js --grep "should work"
+```
+
+## Working on Documentations
+
+The documentations of Leoric is served with Github Pages, which requries Jekyll to build. [It is recommend](https://www.moncefbelyamani.com/the-definitive-guide-to-installing-ruby-gems-on-a-mac/) installing latest Ruby with HomeBrew:
+
+```bash
+$ brew install ruby
+$ echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
+$ cd docs
+$ bundle install
+```
+
+If your network struggles to connect to https://rubygems.org, consider changing the Ruby Gems source in `docs/Gemfile`:
+
+```diff
+diff --git a/docs/Gemfile b/docs/Gemfile
+index 4382725..b4dba82 100644
+--- a/docs/Gemfile
++++ b/docs/Gemfile
+@@ -1,4 +1,4 @@
+-source "https://rubygems.org"
++source "https://gems.ruby-china.com"
+```
+
+When bundle install completes, you can now build docs locally:
+
+```bash
+$ cd docs  # if you're not at this directory yet
+$ jekyll serve
+Configuration file: leoric/docs/_config.yml
+            Source: leoric/docs
+       Destination: leoric/docs/_site
+ Incremental build: disabled. Enable with --incremental
+      Generating...
+   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
+                    done in 3.73 seconds.
+ Auto-regeneration: enabled for 'leoric/docs'
+    Server address: http://127.0.0.1:4000/leoric/
+  Server running... press ctrl-c to stop.
+```
+
+The documentation will be available at <http://localhost:4000/leoric/>.
+
+## How the code is organized
+
+The code basically breaks into following layers (from bottom to top):
+
+- the SQL parser `lib/expr.js`
+- the SQL intermediate representation `lib/spell.js`, which breaks SQL into accessible properties
+- the SQL driver `lib/drivers/*.js`, which generates vendor specific SQLs then queries said SQLs
+- the Bone `lib/bone.js`, which serve as the base model
+- and the optional adapter for sequelize `lib/sequelize.js`
+
+### SQL Drivers
+
+The model driver provides following abilities:
+
+- Attributes in model definition `lib/drivers/*/attribute.js`
+- Data types in model definition `lib/drivers/*/data_types.js`
+- SQL formatters that deal with table structure `lib/drivers/*/schema.js`
+- SQL formatters that translate Spell, the SQL intermediate representation, into vendor specific SQLs `lib/drivers/*/spellbook.js`
+- The exported driver that have them assembled together, `lib/drivers/*/index.js`

docs/index.md

@@ -39,6 +39,41 @@ async function() {
 }
 ```
 
+## Use in Web Frameworks
+
+Leoric can be used in many web frameworkds from Node.js community. If you are developing with egg framework, it is highly recommended using the egg-orm plugin:
+
+```javascript
+/* config/plugin.js */
+exports.orm = {
+  enable: true,
+  package: 'egg-orm',
+};
+
+/* config/config.default.js */
+exports.orm = {
+  client: 'mysql',
+  database: 'temp',
+  host: 'localhost',
+  models: 'app/model',
+};
+```
+
+The models defined in `app/model` will be accessible from `ctx.orm`, such as `ctx.orm.User`:
+
+```javascript
+// app/controller/home.js
+const { Controller } = require('egg');
+module.exports = class HomeController extends Controller {
+  async index() {
+    const users = await ctx.orm.User.find({
+      corpId: ctx.orm.Corp.findOne({ name: 'alipay' }),
+    });
+    ctx.body = users;
+  }
+};
+```
+
 ## Syntax Table
 
 <table class="syntax-table">
@@ -308,3 +343,23 @@ For detailed informations, please check out following guides accordingly:
 5. [Query Interfaces]({{ '/querying' | relative_url }})
 6. [Hooks]({{ '/hooks' | relative_url }})
 7. [Sequelize Adapter]({{ '/sequelize' | relative_url }})
+
+## Contributing
+
+There are many ways in which you can participate in the project, for example:
+
+- [Submit bugs and feature requests](https://github.com/cyjake/leoric/issues), and help us verify as they are checked in
+- [Review source code changes](https://github.com/cyjake/leoric/pulls)
+- Review the [documentation]({{ '/' | relative_url }}) and make pull requests for anything from typo to new content
+
+If you are interested in fixing issues and contributing directly to the code base, please see the document [How to Contribute]({{ '/contributing/guides' | relative_url }}), which covers the following:
+
+- The development workflow, including debugging and running tests
+- Coding guidelines
+- Submitting pull requests
+- Contributing to translations
+
+## Related Projects
+
+If developing web applications with [egg framework](https://eggjs.org/), it's highly recommended using the [egg-orm](https://github.com/eggjs/egg-orm) plugin.
+