Prepare release (#4)

* Add customization options documentation to the README.

* Update contributing guide and add composer script for running tests locally

* Fix some formatting

* Fix links to new org

CONTRIBUTING.md

@@ -1,4 +1,8 @@
-# How to become a contributor and submit your own code
+# Contributing to OpenCensus for PHP
+
+1. **Sign one of the contributor license agreements below.**
+2. Fork the repo, develop, and test your code changes.
+3. Send a pull request.
 
 ## Contributor License Agreements
 
@@ -9,26 +13,57 @@ Please fill out either the individual or corporate Contributor License Agreement
 (CLA).
 
   * If you are an individual writing original source code and you're sure you
-    own the intellectual property, then you'll need to sign an [individual CLA]
-    (https://developers.google.com/open-source/cla/individual).
+    own the intellectual property, then you'll need to sign an
+    [individual CLA](https://developers.google.com/open-source/cla/individual).
   * If you work for a company that wants to allow you to contribute your work,
-    then you'll need to sign a [corporate CLA]
-    (https://developers.google.com/open-source/cla/corporate).
+    then you'll need to sign a
+    [corporate CLA](https://developers.google.com/open-source/cla/corporate).
 
 Follow either of the two links above to access the appropriate CLA and
 instructions for how to sign and return it. Once we receive it, we'll be able to
 accept your pull requests.
 
-## Contributing A Patch
-
-1. Submit an issue describing your proposed change to the repo in question.
-1. The repo owner will respond to your issue promptly.
-1. If your proposed change is accepted, and you haven't already done so, sign a
-   Contributor License Agreement (see details above).
-1. Fork the desired repo, develop and test your code changes.
-1. Ensure that your code adheres to the existing style in the sample to which
-   you are contributing. Refer to the
-   [Google Cloud Platform Samples Style Guide]
-   (https://github.com/GoogleCloudPlatform/Template/wiki/style.html) for the
-   recommended coding standards for this organization.
-1. Submit a pull request.
+## Setup
+
+In order to use OpenCensus for PHP, some setup is required!
+
+1. Install PHP. OpenCensus for PHP requires PHP 5.6 or higher. Installation of
+   PHP varies depending on your system. Refer to the
+   [PHP installation and configuration documentation](http://php.net/manual/en/install.php)
+   for detailed instructions.
+
+1. Install [Composer](https://getcomposer.org/download/).
+
+    Composer is a dependency manager for PHP, and is required to isntall and use
+    OpenCensus for PHP.
+
+1. Install the project dependencies.
+
+    ```sh
+    $ composer install
+    ```
+
+## Tests
+
+Tests are a very important part of OpenCensus for PHP. All contributions should
+include tests that ensure the contributed code behaves as expected.
+
+To run all tests, the following command may be invoked:
+
+```sh
+$ composer tests
+```
+
+## Coding Style
+
+Please follow the established coding style in the library. OpenCensus for PHP
+follows the [PSR-2](https://www.php-fig.org/psr/psr-2/) Coding Style.
+
+You can check your code against these rules by running PHPCS with the proper
+ruleset, like this:
+
+```sh
+$ vendor/bin/phpcs --standard=phpcs-ruleset
+```
+
+Coding style checks are run along with the other test suites.

README.md

@@ -3,8 +3,8 @@
 This library provides an [`ExporterInterface`][exporter-interface] for exporting
 Trace data to a Zipkin instance.
 
-[![CircleCI](https://circleci.com/gh/census-instrumentation/opencensus-php-exporter-zipkin.svg?style=svg)](https://circleci.com/gh/census-instrumentation/opencensus-php-exporter-zipkin)
-[![Packagist](https://img.shields.io/packagist/v/opencensus/opencensus-exporter-zipkin.svg)](https://packagist.org/packages/opencensus/opencensus)
+[![CircleCI](https://circleci.com/gh/census-ecosystem/opencensus-php-exporter-zipkin.svg?style=svg)][ci-build]
+[![Packagist](https://img.shields.io/packagist/v/opencensus/opencensus-exporter-zipkin.svg)][packagist-package]
 ![PHP-Version](https://img.shields.io/packagist/php-v/opencensus/opencensus-exporter-zipkin.svg)
 
 ## Installation & basic usage
@@ -26,11 +26,37 @@ Trace data to a Zipkin instance.
 
 ## Customization
 
-TODO: Fill out these instructions
+### Configuring the Zipkin endpoint
+
+You may provide an optional initialization parameter for the Zipkin endpoint.
+This value should be a full URL to the v2 spans endpoint.
+
+```php
+$exporter = new ZipkinExporter('my-service-name', 'http://example.com:9411/api/v2/spans');
+```
+
+### Configuring the local IPv4 or IPv6 address
+
+Zipkin allows you to optionally specify the host IP address of the server that
+is handling the traced requests.
+
+For IPv4:
+
+```php
+// gethostbyname may make a DNS query, so you may want to cache this
+$ipv4 = gethostbyname(gethostname());
+$exporter->setLocalIpv4($ipv4);
+```
+
+Similarly, you may set the local IPv6 address if you can obtain it:
+
+```php
+$exporter->setLocalIpv6($ipv6);
+```
 
 ## Versioning
 
-[![Packagist](https://img.shields.io/packagist/v/opencensus/opencensus-exporter-zipkin.svg)](https://packagist.org/packages/opencensus/opencensus-exporter-zipkin)
+[![Packagist](https://img.shields.io/packagist/v/opencensus/opencensus-exporter-zipkin.svg)][packagist-package]
 
 This library follows [Semantic Versioning][semver].
 
@@ -73,3 +99,5 @@ This is not an official Google product.
 [census-org]: https://github.com/census-instrumentation
 [composer]: https://getcomposer.org/
 [semver]: http://semver.org/
+[ci-build]: https://circleci.com/gh/census-ecosystem/opencensus-php-exporter-zipkin
+[packagist-package]: https://packagist.org/packages/opencensus/opencensus-exporter-zipkin

composer.json

@@ -23,5 +23,8 @@
         "psr-4": {
             "OpenCensus\\Trace\\Exporter\\": "src/"
         }
+    },
+    "scripts": {
+        "tests": "scripts/run_local_tests.sh"
     }
 }

scripts/run_local_tests.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Copyright 2018 OpenCensus Authors
+#
+# Licensed 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.
+
+# A script for installing necessary software on CI systems.
+
+set -e
+
+DIRNAME=$(dirname $0)
+
+# Run unit tests
+$DIRNAME/../vendor/bin/phpunit
+
+# Run code style tests
+$DIRNAME/../vendor/bin/phpcs --standard=$DIRNAME/../phpcs-ruleset.xml -p

tests/unit/ZipkinExporterTest.php

@@ -91,6 +91,19 @@ public function testSpanKind($spanOpts, $kind)
         $this->assertEquals($kind, $spans[0]['kind']);
     }
 
+    public function testUnspecifiedSpanKind()
+    {
+        $span = new Span([
+            'kind' => Span::KIND_UNSPECIFIED
+        ]);
+        $span->setStartTime();
+        $span->setEndTime();
+        $exporter = new ZipkinExporter('myapp');
+        $spans = $exporter->convertSpans([$span->spanData()]);
+
+        $this->assertArrayNotHasKey('kind', $spans[0]);
+    }
+
     public function spanOptionsForKind()
     {
         return [
@@ -99,8 +112,7 @@ public function spanOptionsForKind()
             [['name' => 'span3', 'timeEvents' => [new MessageEvent(MessageEvent::TYPE_RECEIVED, '')]], 'SERVER'],
             [['name' => 'span4', 'timeEvents' => [new MessageEvent(MessageEvent::TYPE_SENT, '')]], 'CLIENT'],
             [['kind' => Span::KIND_SERVER], 'SERVER'],
-            [['kind' => Span::KIND_CLIENT], 'CLIENT'],
-            [['kind' => Span::KIND_UNSPECIFIED], null]
+            [['kind' => Span::KIND_CLIENT], 'CLIENT']
         ];
     }
 
@@ -176,4 +188,4 @@ public function testSetsLocalEndpointPort()
         $this->assertArrayHasKey('port', $endpoint);
         $this->assertEquals(80, $endpoint['port']);
     }
-}
+}