You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by rx...@apache.org on 2019/08/13 06:56:43 UTC
[pulsar-client-go] branch master updated: Improve README.md and add
CONTRIBUTING.md file (#51)
This is an automated email from the ASF dual-hosted git repository.
rxl pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar-client-go.git
The following commit(s) were added to refs/heads/master by this push:
new 670da09 Improve README.md and add CONTRIBUTING.md file (#51)
670da09 is described below
commit 670da091a38f16779aa4a905f95959ee03c6a120
Author: 冉小龙 <ra...@gmail.com>
AuthorDate: Tue Aug 13 14:56:39 2019 +0800
Improve README.md and add CONTRIBUTING.md file (#51)
Signed-off-by: xiaolong.ran <ra...@gmail.com>
Improve README.md and add CONTRIBUTING.md file.
---
.header | 16 +++++++++++
CONTRIBUTING.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.md | 54 ++++++++++++++++++++++++++++++------
3 files changed, 147 insertions(+), 9 deletions(-)
diff --git a/.header b/.header
new file mode 100644
index 0000000..b248758
--- /dev/null
+++ b/.header
@@ -0,0 +1,16 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..7a6e414
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,86 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# How to contribute
+
+If you would like to contribute code to this project you can do so through GitHub by forking the repository and sending a pull request.
+
+This document outlines some of the conventions on development workflow, commit message formatting, contact points and other resources to make it easier to get your contribution accepted.
+
+## Steps to Contribute
+
+Since the `go mod` package management tool is used in this project, your go version is required at **Go1.11+**.
+
+### Fork
+
+Before you start contributing, you need to fork [pulsar-client-go](https://github.com/apache/pulsar) to your github repository.
+
+### Installation
+
+If you don't currently have a go environment installed，install Go according to the installation instructions here: http://golang.org/doc/install
+
+##### mac os && linux
+
+```bash
+$ mkdir -p $HOME/github.com/apache/
+$ cd $HOME/github.com/apache/
+$ git clone git@github.com:[your-github-id]/pulsar-client-go.git
+$ cd pulsar-client-go
+$ go mod download
+```
+
+When you execute `go mod download`, there may be some libs that cannot be downloaded. You can download them by referring to the proxy provided by [GOPROXY.io](https://goproxy.io/).
+
+### Contribution flow
+
+```bash
+$ git remote add apache git@github.com:apache/pulsar-client-go.git
+
+// sync with remote master
+$ git checkout master
+$ git fetch apache
+$ git rebase apache/master
+$ git push origin master
+
+// create PR branch
+$ git checkout -b your_branch
+# do your work, and then
+$ git add [your change files]
+$ git commit -sm "xxx"
+$ git push origin your_branch
+```
+
+Thanks for your contributions!
+
+#### Code style
+
+The coding style suggested by the Golang community is used in Apache pulsar-client-go. See the [style doc](https://github.com/golang/go/wiki/CodeReviewComments) for details.
+
+Please follow this style to make your pull request easy to review, maintain and develop.
+
+#### Create new file
+
+The project uses the open source protocol of Apache License 2.0. When you need to create a new file when developing new features,
+please add it at the beginning of the file. The location of the header file: [header file](.header).
+
+#### Updating dependencies
+
+Apache `pulsar-client-go` uses [Go 1.11 module](https://github.com/golang/go/wiki/Modules) to manage dependencies. To add or update a dependency: use the `go mod edit` command to change the dependency.
diff --git a/README.md b/README.md
index 8c48e16..f7a2953 100644
--- a/README.md
+++ b/README.md
@@ -24,9 +24,7 @@
[](https://github.com/apache/pulsar-client-go/blob/master/LICENSE)
# Apache Pulsar Go Client Library
-> Note: this library is still a work in progress. For production usage, please
-refer to the CGo based client library, documented at
-http://pulsar.apache.org/docs/en/client-libraries-go/
+A Go client library for the [Apache Pulsar](https://pulsar.incubator.apache.org/) project.
## Goal
@@ -36,6 +34,10 @@ depend on the C++ Pulsar library.
Once feature parity and stability are reached, this will supersede the current
CGo based library.
+## Requirements
+
+- Go 1.11+
+
## Status
Check the Projects page at https://github.com/apache/pulsar-client-go/projects for
@@ -49,11 +51,15 @@ Import the client library:
import "github.com/apache/pulsar-client-go/pulsar"
```
+Create a Producer:
+
```go
client, err := pulsar.NewClient(pulsar.ClientOptions{
URL: "pulsar://localhost:6650",
})
+defer client.Close()
+
producer, err := client.CreateProducer(pulsar.ProducerOptions{
Topic: "my-topic",
})
@@ -62,13 +68,45 @@ err = producer.Send(context.Background(), &pulsar.ProducerMessage{
Payload: []byte("hello"),
})
-if err == nil {
- fmt.Println("Published message")
-} else {
- fmt.Println("Failed to publish message", err)
+defer producer.Close()
+
+if err != nil {
+ fmt.Println("Failed to publish message", err)
}
+fmt.Println("Published message")
+```
+
+Create a Consumer:
+
+```go
+client, err := pulsar.NewClient(pulsar.ClientOptions{
+ URL: "pulsar://localhost:6650",
+})
+
+defer client.Close()
+
+consumer, err := client.Subscribe(pulsar.ConsumerOptions{
+ Topic: "my-topic",
+ SubscriptionName: "my-sub",
+ Type: pulsar.Shared,
+ })
+
+defer consumer.Close()
+
+msg, err := consumer.Receive(context.Background())
+ if err != nil {
+ log.Fatal(err)
+ }
+
+fmt.Printf("Received message msgId: %#v -- content: '%s'\n",
+ msg.ID(), string(msg.Payload()))
+
```
+## Contributing
+
+Contributions are welcomed and greatly appreciated. See [CONTRIBUTING.md](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
+
## Contact
##### Mailing lists
@@ -87,5 +125,3 @@ You can self-register at https://apache-pulsar.herokuapp.com/
## License
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
-
-