Update docs (#31)

* Update README to show v1 examples

Signed-off-by: Dustin Ingram <[email protected]>

* Update release process

Signed-off-by: Dustin Ingram <[email protected]>

* Update CHANGELOG

Signed-off-by: Dustin Ingram <[email protected]>

Author: di

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0]
 ### Added
 - Added Cloudevents V0.3 and V1 implementations ([#22])
 - Add helpful text to README ([#23])
@@ -45,7 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release
 
-[Unreleased]: https://github.com/cloudevents/sdk-python/compare/0.2.4...HEAD
+[0.3.0]: https://github.com/cloudevents/sdk-python/compare/0.2.4...HEAD
 [0.2.4]: https://github.com/cloudevents/sdk-python/compare/0.2.3...0.2.4
 [0.2.3]: https://github.com/cloudevents/sdk-python/compare/0.2.2...0.2.3
 [0.2.2]: https://github.com/cloudevents/sdk-python/compare/0.2.1...0.2.2

README.md

@@ -6,77 +6,106 @@ This SDK is still considered a work in progress, therefore things might (and
 will) break with every update.
 
 This SDK current supports the following versions of CloudEvents:
+- v1.0
+- v0.3
 - v0.2
 - v0.1
 
 ## Python SDK
 
 Package **cloudevents** provides primitives to work with CloudEvents specification: https://github.com/cloudevents/spec.
 
-Parsing upstream Event from HTTP Request:
+Parsing upstream structured Event from HTTP request:
+
 ```python
 import io
 
-from cloudevents.sdk.event import v02
+from cloudevents.sdk.event import v1
 from cloudevents.sdk import marshaller
 
 m = marshaller.NewDefaultHTTPMarshaller()
+
 event = m.FromRequest(
-    v02.Event(),
+    v1.Event(),
+    {"content-type": "application/cloudevents+json"},
+    io.StringIO(
+        """
+        {
+            "specversion": "1.0",
+            "datacontenttype": "application/json",
+            "type": "word.found.name",
+            "id": "96fb5f0b-001e-0108-6dfe-da6e2806f124",
+            "time": "2018-10-23T12:28:22.4579346Z",
+            "source": "<source-url>"
+        }
+        """
+    ),
+    lambda x: x.read(),
+)
+```
+
+Parsing upstream binary Event from HTTP request:
+
+```python
+import io
+
+from cloudevents.sdk.event import v1
+from cloudevents.sdk import marshaller
+
+m = marshaller.NewDefaultHTTPMarshaller()
+
+event = m.FromRequest(
+    v1.Event(),
     {
-        "content-type": "application/cloudevents+json",
-        "ce-specversion": "0.2",
-        "ce-time": "2018-10-23T12:28:22.4579346Z",
+        "ce-specversion": "1.0",
+        "content-type": "application/json",
+        "ce-type": "word.found.name",
         "ce-id": "96fb5f0b-001e-0108-6dfe-da6e2806f124",
+        "ce-time": "2018-10-23T12:28:22.4579346Z",
         "ce-source": "<source-url>",
-        "ce-type": "word.found.name",
     },
-    io.BytesIO(b"this is where your CloudEvent data"), 
-    lambda x: x.read()
+    io.BytesIO(b"this is where your CloudEvent data"),
+    lambda x: x.read(),
 )
-
 ```
 
 Creating a minimal CloudEvent in version 0.1:
+
 ```python
-from cloudevents.sdk.event import v01
+from cloudevents.sdk.event import v1
 
 event = (
-    v01.Event().
-    SetContentType("application/json").
-    SetData('{"name":"john"}').
-    SetEventID("my-id").
-    SetSource("from-galaxy-far-far-away").
-    SetEventTime("tomorrow").
-    SetEventType("cloudevent.greet.you")
+    v1.Event()
+    .SetContentType("application/json")
+    .SetData('{"name":"john"}')
+    .SetEventID("my-id")
+    .SetSource("from-galaxy-far-far-away")
+    .SetEventTime("tomorrow")
+    .SetEventType("cloudevent.greet.you")
 )
-
 ```
 
 Creating HTTP request from CloudEvent:
+
 ```python
 from cloudevents.sdk import converters
 from cloudevents.sdk import marshaller
 from cloudevents.sdk.converters import structured
-from cloudevents.sdk.event import v01
+from cloudevents.sdk.event import v1
 
 event = (
-    v01.Event().
-    SetContentType("application/json").
-    SetData('{"name":"john"}').
-    SetEventID("my-id").
-    SetSource("from-galaxy-far-far-away").
-    SetEventTime("tomorrow").
-    SetEventType("cloudevent.greet.you")
-)
-m = marshaller.NewHTTPMarshaller(
-    [
-        structured.NewJSONHTTPCloudEventConverter()
-    ]
+    v1.Event()
+    .SetContentType("application/json")
+    .SetData('{"name":"john"}')
+    .SetEventID("my-id")
+    .SetSource("from-galaxy-far-far-away")
+    .SetEventTime("tomorrow")
+    .SetEventType("cloudevent.greet.you")
 )
 
-headers, body = m.ToRequest(event, converters.TypeStructured, lambda x: x)
+m = marshaller.NewHTTPMarshaller([structured.NewJSONHTTPCloudEventConverter()])
 
+headers, body = m.ToRequest(event, converters.TypeStructured, lambda x: x)
 ```
 
 ## HOWTOs with various Python HTTP frameworks
@@ -85,7 +114,7 @@ In this topic you'd find various example how to integrate an SDK with various HT
 
 ### Python requests
 
-One of popular framework is [0.2-force-improvements](http://docs.python-requests.org/en/master/).
+One of popular framework is [`requests`](http://docs.python-requests.org/en/master/).
 
 
 #### CloudEvent to request

release.sh

@@ -1,8 +1,35 @@
 #!/usr/bin/env bash
 
+# Fail fast and fail hard.
+set -eo pipefail
 
+# Check for our version
+if [ -z "$CLOUDEVENTS_SDK_VERSION" ]; then
+    echo "Need to set CLOUDEVENTS_SDK_VERSION"
+    exit 1
+fi
+
+# Run tests on target branch
+tox
+
+# Cut off stable branch
 git checkout -b v${CLOUDEVENTS_SDK_VERSION}-stable
+
+# Create GitHub tag
+git tag -a ${CLOUDEVENTS_SDK_VERSION} -m "${CLOUDEVENTS_SDK_VERSION}"
+
+# Build distribution package
+rm -rf dist
+pip install -U setuptools wheel
+python setup.py sdist bdist_wheel
+
+# Submit relase to PyPI
+pip install -U twine
+twine upload dist/*
+
+# Push the release to GitHub
 git push origin v${CLOUDEVENTS_SDK_VERSION}-stable
-PBR_VERSION=${CLOUDEVENTS_SDK_VERSION} python setup.py sdist bdist_wheel
-twine upload dist/cloudevents-${CLOUDEVENTS_SDK_VERSIONN}*
+git push --tags
+
+# Switch back to the master branch
 git checkout master

release_doc.md

@@ -1,66 +1,60 @@
-Release process
-===============
+# Release process
 
-Run tests on target brunch
---------------------------
+## Run tests on target branch
 
 Steps:
 
     tox
 
-Cut off stable branch
----------------------
+## Cut off stable branch
 
 Steps:
 
     git checkout -b vX.X.X-stable
-    git push origin vX.X.X-stable
 
 
-Create GitHub tag
------------------
+## Create GitHub tag
 
 Steps:
 
-    Releases ---> Draft New Release
-    Name: CloudEvents Python SDK version X.X.X stable release
+    git tag -a X.X.X -m "X.X.X"
 
 
-Collect changes from previous version
--------------------------------------
+## Build distribution package
 
 Steps:
 
-    git log --oneline --decorate
+    rm -rf dist
+    pip install -U setuptools wheel
+    python setup.py sdist bdist_wheel
 
 
-Build distribution package
---------------------------
+## Check install capability for the wheel
 
 Steps:
 
-    PBR_VERSION=X.X.X python setup.py sdist bdist_wheel
+    python3.7 -m venv .test_venv
+    source .test_venv/bin/activate
+    pip install dist/cloudevents-X.X.X-py3-none-any.whl
 
 
-Check install capability for the wheel
---------------------------------------
+## Submit release to PyPI
 
 Steps:
 
-    python3.7 -m venv .test_venv
-    source .test_venv/bin/activate
-    pip install dist/cloudevents-X.X.X-py3-none-any.whl
+    pip install -U twine
+    twine upload dist/*
 
 
-Submit release to PYPI
-----------------------
+## Push the release to GitHub
 
 Steps:
 
-    twine upload dist/cloudevents-X.X.X-py3-none-any.whl
+    git push origin vX.X.X-stable
+    git push --tags
+
 
-Verify install capability for the wheel
----------------------------------------
+## Verify install capability for the wheel
 
 Steps:
 

setup.cfg

@@ -24,3 +24,6 @@ packages =
 [global]
 setup-hooks =
     pbr.hooks.setup_hook
+
+[pbr]
+skip_changelog = True