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: 冉小龙 <ranxiaolong...@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 <ranxiaolong...@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 g...@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 g...@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 @@ [![LICENSE](https://img.shields.io/hexpm/l/pulsar.svg)](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 - -