From fa017b597708810f5027bb18232763a7f97a7b66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=96=E7=95=8C?= Date: Thu, 25 Aug 2022 21:08:29 +0800 Subject: [PATCH] Add contributing documentation --- docs/configuration/dns/index.md | 2 + docs/configuration/experimental/index.md | 2 + docs/configuration/inbound/index.md | 2 + docs/configuration/outbound/index.md | 2 + docs/configuration/route/index.md | 2 + docs/contributing/environment.md | 50 +++++++++++++++ docs/contributing/index.md | 17 ++++++ docs/contributing/sub-projects.md | 78 ++++++++++++++++++++++++ docs/index.md | 4 ++ docs/index.zh.md | 4 ++ mkdocs.yml | 7 ++- 11 files changed, 169 insertions(+), 1 deletion(-) create mode 100644 docs/contributing/environment.md create mode 100644 docs/contributing/index.md create mode 100644 docs/contributing/sub-projects.md diff --git a/docs/configuration/dns/index.md b/docs/configuration/dns/index.md index 94780088..f6889dd7 100644 --- a/docs/configuration/dns/index.md +++ b/docs/configuration/dns/index.md @@ -1,3 +1,5 @@ +# DNS + ### Structure ```json diff --git a/docs/configuration/experimental/index.md b/docs/configuration/experimental/index.md index 8a369322..9a9792a6 100644 --- a/docs/configuration/experimental/index.md +++ b/docs/configuration/experimental/index.md @@ -1,3 +1,5 @@ +# Experimental + ### Structure ```json diff --git a/docs/configuration/inbound/index.md b/docs/configuration/inbound/index.md index 7b1909ae..0475ba58 100644 --- a/docs/configuration/inbound/index.md +++ b/docs/configuration/inbound/index.md @@ -1,3 +1,5 @@ +# Inbound + ### Structure ```json diff --git a/docs/configuration/outbound/index.md b/docs/configuration/outbound/index.md index 1db484ad..78686888 100644 --- a/docs/configuration/outbound/index.md +++ b/docs/configuration/outbound/index.md @@ -1,3 +1,5 @@ +# Outbound + ### Structure ```json diff --git a/docs/configuration/route/index.md b/docs/configuration/route/index.md index 7593fe8d..0b541c76 100644 --- a/docs/configuration/route/index.md +++ b/docs/configuration/route/index.md @@ -1,3 +1,5 @@ +# Route + ### Structure ```json diff --git a/docs/contributing/environment.md b/docs/contributing/environment.md new file mode 100644 index 00000000..dc6487ef --- /dev/null +++ b/docs/contributing/environment.md @@ -0,0 +1,50 @@ +# Development environment + +#### For the documentation + +##### Setup + +You need to configure python3 and pip first. + +```shell +pip install mkdocs-material mkdocs-static-i18n +``` + +##### Run the site locally + +```shell +mkdocs serve +``` + +or + +```shell +python3 -m mkdocs serve +``` + +#### For the project + +By default you have the latest Go installed (currently 1.19), and added `GOPATH/bin` to the PATH environment variable. + +##### Setup + +```shell +make fmt_insall +make lint_install +``` + +This installs the formatting and lint tools, which can be used via `make fmt` and `make lint`. + +For ProtoBuffer changes, you also need `make proto_install` and `make proto`. + +##### Build binary to the project directory + +```shell +make +``` + +##### Install binary to GOPATH/bin + +```shell +make install +``` \ No newline at end of file diff --git a/docs/contributing/index.md b/docs/contributing/index.md new file mode 100644 index 00000000..d669bda6 --- /dev/null +++ b/docs/contributing/index.md @@ -0,0 +1,17 @@ +# Contributing to sing-box + +An introduction to contributing to the sing-box project. + +The sing-box project welcomes, and depends, on contributions from developers and users in the open source community. +Contributions can be made in a number of ways, a few examples are: + +* Code patches via pull requests +* Documentation improvements +* Bug reports and patch reviews + +### Reporting an Issue? + +Please follow +the [issue template](https://github.com/SagerNet/sing-box/issues/new?assignees=&labels=&template=bug_report.yml) to +submit bugs. Always include **FULL** log content, especially if you don't understand the code that generates it. + diff --git a/docs/contributing/sub-projects.md b/docs/contributing/sub-projects.md new file mode 100644 index 00000000..c10306fe --- /dev/null +++ b/docs/contributing/sub-projects.md @@ -0,0 +1,78 @@ +The sing-box uses the following projects which also need to be maintained: + +#### sing + +Link: [GitHub repository](https://github.com/SagerNet/sing) + +As a base tool library, there are no dependencies other than `golang.org/x/sys`. + +#### sing-dns + +Link: [GitHub repository](https://github.com/SagerNet/sing-dns) + +Handles DNS lookups and caching. + +#### sing-tun + +Link: [GitHub repository](https://github.com/SagerNet/sing-tun) + +Handle Tun traffic forwarding, configure routing, monitor network and routing. + +This library needs to periodically update its dependency gVisor (according to tags), including checking for changes to +the used parts of the code and updating its usage. If you are involved in maintenance, you also need to check that if it +works or contains memory leaks. + +#### sing-shadowsocks + +Link: [GitHub repository](https://github.com/SagerNet/sing-shadowsocks) + +Provides Shadowsocks client and server + +#### sing-vmess + +Link: [GitHub repository](https://github.com/SagerNet/sing-vmess) + +Provides VMess client and server + +#### netlink + +Link: [GitHub repository](https://github.com/SagerNet/netlink) + +Fork of `vishvananda/netlink`, with some rule fixes. + +The library needs to be updated with the upstream. + +#### quic-go + +Link: [GitHub repository](https://github.com/SagerNet/quic-go) + +Fork of `lucas-clemente/quic-go` and `HyNetwork/quic-go`, contains quic flow control and other fixes used by Hysteria. + +Since the author of Hysteria does not follow the upstream updates in time, and the provided fork needs to use replace, +we need to do this. + +The library needs to be updated with the upstream. + +#### certmagic + +Link: [GitHub repository](https://github.com/SagerNet/certmagic) + +Fork of `caddyserver/certmagic` + +Since upstream uses `miekg/dns` and we use `x/net/dnsmessage`, we need to replace its DNS part with our own +implementation. + +The library needs to be updated with the upstream. + +#### smux + +Link: [GitHub repository](https://github.com/SagerNet/smux) + +Fork of `xtaci/smux` + +Modify the code to support the writev it uses internally and unify the buffer pool, which prevents it from allocating +64k buffers for per connection and improves performance. + +Upstream doesn't seem to be updated anymore, maybe a replacement is needed. + +Note: while yamux is still actively maintained and better known, it seems to be less performant. diff --git a/docs/index.md b/docs/index.md index 1dcfff4a..080d58a0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,7 @@ +--- +description: Welcome to the wiki page for the sing-box project. +--- + # Home Welcome to the wiki page for the sing-box project. diff --git a/docs/index.zh.md b/docs/index.zh.md index 84dcb96c..ac7b716b 100644 --- a/docs/index.zh.md +++ b/docs/index.zh.md @@ -1,3 +1,7 @@ +--- +description: 欢迎来到该 sing-box 项目的文档页。 +--- + # 开始 欢迎来到该 sing-box 项目的文档页。 diff --git a/mkdocs.yml b/mkdocs.yml index 36331602..3ae83225 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,7 +49,7 @@ nav: - Route Rule: configuration/route/rule.md - Protocol Sniff: configuration/route/sniff.md - Experimental: - - configuration/experimental/index.md + - configuration/experimental/index.md - Shared: - TLS: configuration/shared/tls.md - Multiplex: configuration/shared/multiplex.md @@ -93,6 +93,11 @@ nav: - Shadowsocks Client: examples/ss-client.md - Shadowsocks Tun: examples/ss-tun.md - DNS Hijack: examples/dns-hijack.md + - Contributing: + - contributing/index.md + - Developing: + - Environment: contributing/environment.md + - Sub projects: contributing/sub-projects.md markdown_extensions: - pymdownx.inlinehilite - pymdownx.snippets