This is an automated email from the ASF dual-hosted git repository.
tison pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new ad8eea9f85d Migrate coding-guide (#356)
ad8eea9f85d is described below
commit ad8eea9f85d8be8dc9329d72934b866ac0a88565
Author: tison <[email protected]>
AuthorDate: Sun Jan 1 19:03:01 2023 +0800
Migrate coding-guide (#356)
Signed-off-by: tison <[email protected]>
---
contribute/about.md | 2 +-
.../develop-coding-conventions.md | 41 ++++++++++------------
contribute/develop-labels.md | 2 +-
contribute/develop-semantic-title.md | 2 +-
docker-compose.yaml | 2 +-
sidebarsDevelopment.js | 1 +
static/.htaccess | 7 ++--
{scripts => tools/conf}/httpd.conf | 0
8 files changed, 28 insertions(+), 29 deletions(-)
diff --git a/contribute/about.md b/contribute/about.md
index ebd75f8dddf..c1c9673d316 100644
--- a/contribute/about.md
+++ b/contribute/about.md
@@ -6,7 +6,7 @@ sidebar_label: "About"
sidebar_position: 2
---
-This guide is a comprehensive resource for contributing to Apache Pulsar – for
both new and experienced contributors. It is maintained by the same community
that maintains Pulsar. We welcome your contributions to Pulsar!
+The Apache Pulsar community welcomes contributions from anyone with a passion
for distributed systems! Pulsar has many opportunities for contributions: write
new examples/tutorials, add new user-facing libraries, write new Pulsar IO
connectors, or participate on the documentation effort.
## Quick Links
diff --git a/src/pages/coding-guide.md
b/contribute/develop-coding-conventions.md
similarity index 53%
rename from src/pages/coding-guide.md
rename to contribute/develop-coding-conventions.md
index 59b14fbac01..01a326b4815 100644
--- a/src/pages/coding-guide.md
+++ b/contribute/develop-coding-conventions.md
@@ -1,18 +1,14 @@
---
-id: head-metadata
-title: Coding Guide
-description: Coding Guide
-hide_table_of_contents: true
+id: develop-coding-conventions
+title: Coding conventions
---
-# Coding Guide
-The guidelines help to encourage consistency and best practices among people
working on _Apache Pulsar_ code base. You should observe the guidelines unless
there is compelling reason to ignore them. We use checkstyle to enforce coding
style, refer to our [checkstyle
rules](https://github.com/apache/pulsar/blob/master/buildtools/src/main/resources/pulsar/checkstyle.xml)
for all enforced checkstyle rules.
+The guidelines help to encourage consistency and best practices among people
working on Apache Pulsar code base. You should observe the guidelines unless
there is compelling reason to ignore them. Pulsar uses checkstyle to enforce
coding style, refer to our [checkstyle
rules](https://github.com/apache/pulsar/blob/master/buildtools/src/main/resources/pulsar/checkstyle.xml)
for all enforced checkstyle rules.
-## Java
+## Java code style
Apache Pulsar code follows the [Sun Java Coding
Convention](http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html),
with the following additions.
-* Lines can not be longer than 120 characters.
* Indentation should be **4 spaces**. Tabs should never be used.
* Use curly braces even for single-line ifs and elses.
* No @author tags in any javadoc.
@@ -23,34 +19,34 @@ Apache Pulsar code follows the [Sun Java Coding
Convention](http://www.oracle.co
Apache Pulsar uses the following libraries a lot:
-* [Guava](https://github.com/google/guava): as a fundamental core library
-* [Netty](http://netty.io/): for network communications and memory buffer
management.
+* [Guava](https://github.com/google/guava) as a fundamental core library
+* [Netty](http://netty.io/) for network communications and memory buffer
management.
Use these libraries whenever possible rather than introducing more
dependencies.
-Dependencies are bundled with our binary distributions, so we need to attach
the relevant licenses. See [Third party dependencies and
licensing](https://pulsar.apache.org/docs/en/client-libraries/) for a guide on
how to do it correctly.
+Dependencies are bundled with our binary distributions, so you need to attach
the relevant licenses when adding new dependencies.
## Future
-Java-8 Future is preferred over Guava's Listenable Future. Use Java-8 Future
whenever possible.
+`CompletableFuture` introduce in Java 8 is preferred over Guava's
`ListenableFuture`. Use `CompletableFuture` whenever possible.
## Memory
-Use netty _ByteBuf_ over java nio _ByteBuffer_ for internal usage. As we are
using Netty Buffer for memory management.
+Use netty `ByteBuf` over `java.nio.ByteBuffer` for internal usage. As Pulsar
uses Netty Buffer for memory management.
## Logging
* Logging should be taken seriously. Please take the time to access the logs
when making a change to ensure that the important things are getting logged and
there is no junk there.
* Logging statements should be complete sentences with proper capitalization
that are written to be read by a person not necessarily familiar with the
source code.
-* All loggings should be done with **SLF4j**, never _System.out_ or
_System.err_.
+* All logs should be done with **SLF4j**, never `System.out` or `System.err`.
### Logging levels
-- _INFO_ is the level you should assume the software will be run in. INFO
messages are things which are not bad but which the user will definitely want
to know about every time they occur.
-- _TRACE_ and _DEBUG_ are both things you turn on when something is wrong and
you want to figure out what is going on. _DEBUG_ should not be so fine grained
that it will seriously affect performance of the program. _TRACE_ can be
anything. You should wrap _DEBUG_ and _TRACE_ statements in the `if
(logger.isDebugEnabled)` or `if (logger.isTraceEnabled)` check to avoid
performance degradation.
-- _WARN_ and _ERROR_ indicate something that is **BAD**. Use _WARN_ if you
aren't totally sure it is bad, and _ERROR_ if you are.
+* **INFO** is the level you should assume the software will be run in. INFO
messages are things which are not bad but which the user will definitely want
to know about every time they occur.
+* **TRACE** and **DEBUG** are both things you turn on when something is wrong,
and you want to figure out what is going on. **DEBUG** should not be so
fine-grained that it will seriously affect performance of the program.
**TRACE** can be anything. You should wrap DEBUG and TRACE statements in the
`if (logger.isDebugEnabled())` or `if (logger.isTraceEnabled())` check to avoid
performance degradation.
+* **WARN** and **ERROR** indicate something that is *BAD*. Use WARN if you
aren't totally sure it is bad, and ERROR if you are.
-Log the _stack traces_ at **ERROR** level, but never at **INFO** level or
below. You can log at **WARN** level if you are interested in debugging.
+Log the stack traces at **ERROR** level, but never at **INFO** level or below.
You can log at **WARN** level if you are interested in debugging.
## Monitoring
@@ -61,10 +57,10 @@ Log the _stack traces_ at **ERROR** level, but never at
**INFO** level or below.
* New changes should come with unit tests that verify the functionality being
added.
* Unit tests should test the least amount of code possible. Don't start the
whole server unless there is no other way to test a single class or small group
of classes in isolation.
-* Tests should not depend on any external resources. They need to setup and
teardown their own stuff.
+* Tests should not depend on any external resources. They need to set up and
teardown their own stuff.
* It is okay to use the filesystem and network in tests since that's our
business, but you need to clean up them after test.
-* _Do not_ use sleep or other timing assumptions in tests. It is wrong and
will fail intermittently on any test server with other things going on that
causes delays.
-* You'd better add a _timeout_ value to all test cases, to prevent a build
from completing indefinitely. For example, `@Test(timeout=60000)`
+* DO NOT use sleep or other timing assumptions in tests. It is wrong and will
fail intermittently on any test server with other things going on that causes
delays.
+* You'd better add a timeout value to all test cases, to prevent a build from
completing indefinitely. For example, `@Test(timeout=60000)`.
## Configuration
@@ -77,11 +73,12 @@ Log the _stack traces_ at **ERROR** level, but never at
**INFO** level or below.
Apache Pulsar is a low latency system, it is implemented as a purely
asynchronous service, which is accomplished as follows:
* All public classes should be **thread-safe**.
-* We prefer using
[OrderedExecutor](https://github.com/apache/bookkeeper/blob/master/bookkeeper-common/src/main/java/org/apache/bookkeeper/common/util/OrderedExecutor.java)
for executing any asynchronous actions. The mutations to the same instance
should be submitted to the same thread to execute.
+* Prefer using
[OrderedExecutor](https://github.com/apache/bookkeeper/blob/master/bookkeeper-common/src/main/java/org/apache/bookkeeper/common/util/OrderedExecutor.java)
for executing any asynchronous actions. The mutations to the same instance
should be submitted to the same thread to execute.
* If synchronization and locking are required, they should be in a fine
granularity way.
* All threads should have proper meaningful name.
* If a class is not thread-safe, it should be annotated
[@NotThreadSafe](https://github.com/misberner/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/NotThreadSafe.java).
The instances that use this class is responsible for its synchronization.
## Backwards compatibility
+
* Wire protocol should support backwards compatibility to enable no-downtime
upgrades. This means the servers **MUST** be able to support requests from both
old and new clients simultaneously.
* Metadata formats and data formats should support backwards compatibility.
diff --git a/contribute/develop-labels.md b/contribute/develop-labels.md
index 9be9c54d1a6..dfbce8150fc 100644
--- a/contribute/develop-labels.md
+++ b/contribute/develop-labels.md
@@ -1,6 +1,6 @@
---
id: develop-labels
-title: Labels
+title: Label strategy
---
This guide explains the labels used in the
[apache/pulsar](http://github.com/apache/pulsar) repository (the main repo).
diff --git a/contribute/develop-semantic-title.md
b/contribute/develop-semantic-title.md
index d28e751ee76..c4320d86bb7 100644
--- a/contribute/develop-semantic-title.md
+++ b/contribute/develop-semantic-title.md
@@ -1,6 +1,6 @@
---
id: develop-semantic-title
-title: Conventional commits
+title: Semantic pull request
---
This guide explains why you need good PR titles and how you do write PR titles
in Conventional Commits spec.
diff --git a/docker-compose.yaml b/docker-compose.yaml
index b27f1ba2cc2..96efbb104a6 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -23,5 +23,5 @@ services:
- "80:80"
volumes:
- ./build:/usr/local/apache2/htdocs
- - ./scripts/httpd.conf:/usr/local/apache2/conf/httpd.conf
+ - ./tools/conf/httpd.conf:/usr/local/apache2/conf/httpd.conf
container_name: pulsar_site
diff --git a/sidebarsDevelopment.js b/sidebarsDevelopment.js
index 8a4e71b263b..eb90ece8044 100644
--- a/sidebarsDevelopment.js
+++ b/sidebarsDevelopment.js
@@ -14,6 +14,7 @@ const sidebars = {
type: "category",
label: "Development",
items: [
+ 'develop-coding-conventions',
'develop-labels',
'develop-semantic-title'
]
diff --git a/static/.htaccess b/static/.htaccess
index 30a5581990d..27f7cc98c82 100755
--- a/static/.htaccess
+++ b/static/.htaccess
@@ -8,12 +8,13 @@ RewriteRule "^docs$" "/docs/" [R=301,DPI,L]
RewriteRule "^docs/(.+)-incubating/(.+)$"
"https://pulsar.staged.apache.org/docs/$1-incubating/$2"; [R=301,DPI,L]
RewriteRule "^pulsar-manager-release-notes(/)?$" "/release-notes" [R=301,DPI,L]
+RewriteRule "^coding-guide(/)?$" "/contribute/develop-coding-conventions/"
[R=301,DPI,L]
RewriteRule "^docs/(.+/)?security-policy-and-supported-versions(/)?$"
"/contribute/version-policy/" [R=301,DPI,L]
# skip if file exists
RewriteCond %{REQUEST_FILENAME}\/index\.html -f
RewriteRule ^ - [L]
-RewriteRule "^docs/(.+/)?develop-binary-protocol(/)?$"
"/docs/$1developing-binary-protocol$2" [R=301,DPI,L]
-RewriteRule "^docs/(.+/)?administration-dashboard(/)?$"
"/docs/$1administration-pulsar-manager$2" [R=301,DPI,L]
-RewriteRule "^docs/(.+/)?security-tls-keystore(/)?$"
"/docs/$1security-tls-authentication$2" [R=301,DPI,L]
+RewriteRule "^docs/(.+/)?develop-binary-protocol(/)?$"
"/docs/$1developing-binary-protocol" [R=301,DPI,L]
+RewriteRule "^docs/(.+/)?administration-dashboard(/)?$"
"/docs/$1administration-pulsar-manager" [R=301,DPI,L]
+RewriteRule "^docs/(.+/)?security-tls-keystore(/)?$"
"/docs/$1security-tls-authentication" [R=301,DPI,L]
diff --git a/scripts/httpd.conf b/tools/conf/httpd.conf
similarity index 100%
rename from scripts/httpd.conf
rename to tools/conf/httpd.conf
