sharpetronics/drogon
1
0
Fork 0
mirror of https://github.com/drogonframework/drogon.git synced 2025-09-14 00:00:48 -04:00
Code Issues Projects Releases Wiki Activity

Added Initial Contribution Recommendations (#445)

Browse Source 
Co-authored-by: antao <antao2002@gmail.com>
This commit is contained in:
Rafał Bugajewski 2020-05-25 15:05:05 +02:00 committed by GitHub
parent e286fe869a
commit 598d8c15b3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 96 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,78 @@
# Contributing
**Drogon** is an open source project at its heart and every contribution is
welcome. By participating in this project you agree to stick to common sense and
contribute in an overall positive way.
## Getting Started
1. Fork, then clone the repository: `git clone
git@github.com:your-username/drogon.git`
1. Follow the [official installation steps on
DocsForge](https://drogon.docsforge.com/master/installation/). It’s best to
make sure to have the `drogon_ctl` executable in your shell’s `PATH`
environment variable in case you use a terminal.
Now you can create branches, start adding features & bugfixes to the code, and
[create pull requests](https://github.com/an-tao/drogon/compare).
## Pull Requests
Feel free to [create a pull request](https://github.com/an-tao/drogon/compare)
if you think you can contribute to the project. You will be listed as a
[contributor](https://github.com/an-tao/drogon/graphs/contributors), agree to
this document, and the
[LICENSE](https://github.com/an-tao/drogon/blob/master/LICENSE).
There are also some recommendations you can follow. These aren’t requirements,
but they will make the development more straightforward:
1. If you are unsure about a specific change, have questions, or want to get
feedback about a feature you want to introduce, [open a new
issue](https://github.com/an-tao/drogon/issues) (please make sure that there
is no previous issue about a similar topic).
1. You should branch off the current state of the `master` branch, and also
merge it into your local branch before creating a pull request if there were
other changes introduced in the meantime.
1. You can use the following branch names to make your intent clearer:
* `bugfix/123-fix-template-parser` when you want to fix a bug in the
template parser.
* `feature/123-add-l10n-and-i18n` if you want to add localization (l10n) and
internationalization (i18n) as a new feature to the project.
* If there’s no open issue and no need to open one you can skip the number,
and just use the descriptive part: `bugfix/fix-typo-in-docs`.
1. Write a brief, but good, and descriptive commit message / pull request title in English,
e. g. “Added Internationalization and Localization”.
If you follow these recommendations your pull request will have more success:
1. Keep the style consistent to the project, when in doubt refer to the [Google
C++ Style Guide](https://google.github.io/styleguide/cppguide.html#C++_Version).
1. Please write all comments in English. Comments for new public API introduced by
your pull request must be added and written in [Doxygen](http://www.doxygen.nl/) format.
1. Format the code with `clang-format` (>= 8.0.0). The configuration is already
provided in the `.clang-format` file, just run the `./format.sh` script
before submitting your pull request.
1. Install [Google Test](https://github.com/google/googletest), and write a test
case.
1. In case it is a bugfix, it’s best to write a test that breaks in the old
version, but works in the new one. This way regressions can be tracked
over time.
1. If you add a feature, it is best to write the test as if it would be an
example how to use the newly introduced feature and to test all major,
newly introduced code.
## Project Maintainers & Collaborators
In addition to the guidelines mentioned above, collaborators with write access
to the repository should also follow these guidelines:
1. If there are new tests as part of the pull request, you should make sure that
they succeed.
1. When merging **Pull Requests** you should use the option *Squash & Merge* and
chose a descriptive commit message for the bugfix / feature (if not already
done by the individual contributor).
This way the history in the `master` branch will be free of small
corrections and easier to follow for people who aren’t engaged in the
project on a day-to-day basis.

17
README.md
View File

@ -3,16 +3,16 @@
[![Build Status](https://travis-ci.com/an-tao/drogon.svg?branch=master)](https://travis-ci.com/an-tao/drogon)
[![Build status](https://ci.appveyor.com/api/projects/status/12ffuf6j5vankgyb/branch/master?svg=true)](https://ci.appveyor.com/project/an-tao/drogon/branch/master)
[![Total alerts](https://img.shields.io/lgtm/alerts/g/an-tao/drogon.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/an-tao/drogon/alerts/)
[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/an-tao/drogon.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/an-tao/drogon/context:cpp)
[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/an-tao/drogon.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/an-tao/drogon/context:cpp)
[![Join the chat at https://gitter.im/drogon-web/community](https://badges.gitter.im/drogon-web/community.svg)](https://gitter.im/drogon-web/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Docker image](https://img.shields.io/badge/Docker-image-blue.svg)](https://cloud.docker.com/u/drogonframework/repository/docker/drogonframework/drogon)
### Overview
**Drogon** is a C++14/17-based HTTP application framework. Drogon can be used to easily build various types of web application server programs using C++. **Drogon** is the name of a dragon in the American TV series "Game of Thrones" that I really like.
**Drogon** is a C++14/17-based HTTP application framework. Drogon can be used to easily build various types of web application server programs using C++. **Drogon** is the name of a dragon in the American TV series "Game of Thrones" that I really like.
Drogon is a cross-platform framework, It supports Linux, Mac OS, FreeBSD and Windows. Its main features are as follows:
Drogon is a cross-platform framework, It supports Linux, macOS, FreeBSD, and Windows. Its main features are as follows:
* Use a non-blocking I/O network lib based on epoll (kqueue under MacOS/FreeBSD) to provide high-concurrency, high-performance network IO, please visit the [benchmarks](https://github.com/an-tao/drogon/wiki/13-Benchmarks) page and [TFB Live Results](https://tfb-status.techempower.com/) for more details;
* Use a non-blocking I/O network lib based on epoll (kqueue under macOS/FreeBSD) to provide high-concurrency, high-performance network IO, please visit the [benchmarks](https://github.com/an-tao/drogon/wiki/13-Benchmarks) page and [TFB Live Results](https://tfb-status.techempower.com/) for more details;
* Provide a completely asynchronous programming mode;
* Support Http1.0/1.1 (server side and client side);
* Based on template, a simple reflection mechanism is implemented to completely decouple the main program framework, controllers and views.
@ -82,7 +82,7 @@ app.registerHandler("/test?username={name}",
},
{Get,"LoginFilter"});
```
While such interfaces look intuitive, they are not suitable for complex business logic scenarios. Assuming there are tens or even hundreds of handlers that need to be registered in the framework, isn't it a better practice to implement them separately in their respective classes? So unless your logic is very simple, we don't recommend using above interfaces. Instead, we can create an HttpSimpleController as follows:
```c++
@ -177,8 +177,11 @@ class User : public drogon::HttpController<User>
} // namespace api
```
As you can see, users can use the `HttpController` to map paths and parameters at the same time. This is a very convenient way to create a RESTful API application.
As you can see, users can use the `HttpController` to map paths and parameters at the same time. This is a very convenient way to create a RESTful API application.
In addition, you can also find that all handler interfaces are in asynchronous mode, where the response is returned by a callback object. This design is for performance reasons because in asynchronous mode the drogon application can handle a large number of concurrent requests with a small number of threads.
After compiling all of the above source files, we get a very simple web application. This is a good start. **for more information, please visit the [wiki](https://github.com/an-tao/drogon/wiki/01-Overview) or [docsforge](https://drogon.docsforge.com/master/overview/)**
After compiling all of the above source files, we get a very simple web application. This is a good start. **For more information, please visit the [wiki](https://github.com/an-tao/drogon/wiki/01-Overview) or [DocsForge](https://drogon.docsforge.com/master/overview/)**
## Contributions
Every contribution is welcome. Please refer to the [contribution guidelines](CONTRIBUTING.md) for more information.

12
README.zh-CN.md
View File

@ -2,16 +2,16 @@
[![Build Status](https://travis-ci.com/an-tao/drogon.svg?branch=master)](https://travis-ci.com/an-tao/drogon)
[![Total alerts](https://img.shields.io/lgtm/alerts/g/an-tao/drogon.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/an-tao/drogon/alerts/)
[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/an-tao/drogon.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/an-tao/drogon/context:cpp)
[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/an-tao/drogon.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/an-tao/drogon/context:cpp)
[![Join the chat at https://gitter.im/drogon-web/community](https://badges.gitter.im/drogon-web/community.svg)](https://gitter.im/drogon-web/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Docker image](https://img.shields.io/badge/Docker-image-blue.svg)](https://cloud.docker.com/u/drogonframework/repository/docker/drogonframework/drogon)
**Drogon**是一个基于C++14/17的Http应用框架，使用Drogon可以方便的使用C++构建各种类型的Web应用服务端程序。
本版本库是github上[Drogon工程](https://github.com/an-tao/drogon)的镜像库。**Drogon**是作者非常喜欢的美剧《权力的游戏》中的一条龙的名字(汉译作卓耿)，和龙有关但并不是dragon的误写，为了不至于引起不必要的误会这里说明一下。
Drogon是一个跨平台框架，它支持Linux，也支持Mac OS、FreeBSD，和Windows。它的主要特点如下：
Drogon是一个跨平台框架，它支持Linux，也支持macOS、FreeBSD，和Windows。它的主要特点如下：
* 网络层使用基于epoll(MacOS/FreeBSD下是kqueue)的非阻塞IO框架，提供高并发、高性能的网络IO。详细请见[性能测试](https://github.com/an-tao/drogon/wiki/13-%E6%80%A7%E8%83%BD%E6%B5%8B%E8%AF%95)和[TFB Live Results](https://tfb-status.techempower.com/)；
* 网络层使用基于epoll(macOS/FreeBSD下是kqueue)的非阻塞IO框架，提供高并发、高性能的网络IO。详细请见[性能测试](https://github.com/an-tao/drogon/wiki/13-%E6%80%A7%E8%83%BD%E6%B5%8B%E8%AF%95)和[TFB Live Results](https://tfb-status.techempower.com/)；
* 全异步编程模式；
* 支持Http1.0/1.1(server端和client端)；
* 基于template实现了简单的反射机制，使主程序框架、控制器(controller)和视图(view)完全解耦；
@ -176,10 +176,14 @@ class User : public drogon::HttpController<User>
};
} // namespace v1
} // namespace api
```
```
如你所见，通过`HttpController`类，用户可以同时映射路径和路径参数，这对RESTful API应用来说非常方便。
另外，你可以发现前面所有的处理函数接口都是异步的，处理器的响应是通过回调对象返回的。这种设计是出于对高性能的考虑，因为在异步模式下，可以使用少量的线程（比如和处理器核心数相等的线程）处理大量的并发请求。
编译上述的所有源文件后，我们得到了一个非常简单的web应用程序，这是一个不错的开始。**请访问[wiki](https://github.com/an-tao/drogon/wiki/01-Overview)或者[doxiz](https://doxiz.com/drogon/master/overview/)以获取更多的信息**
## 贡献方式
欢迎您的贡献。 请阅读[贡献指南](CONTRIBUTING.md)以获取更多的信息。