Merge pull request #10 from canonical/update_readme

docs: add README and CONTRIBUTING

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing
+
+## Overview
+
+This documents explains the processes and practices recommended for contributing enhancements to this operator.
+
+- Generally, before developing enhancements to this charm, you should consider [opening an issue](https://github.com/canonical/kafka-operator/issues) explaining your problem with examples, and your desired use case.
+- If you would like to chat with us about your use-cases or proposed implementation, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev) or [Discourse](https://discourse.charmhub.io/).
+- Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library will help you a lot when working on new features or bug fixes.
+- All enhancements require review before being merged. Code review typically examines
+  - code quality
+  - test coverage
+  - user experience for Juju administrators this charm.
+- Please help us out in ensuring easy to review branches by rebasing your pull request branch onto the `main` branch. This also avoids merge commits and creates a linear Git commit history.
+
+## Requirements
+
+To build the charm locally, you will need to install [Charmcraft](https://juju.is/docs/sdk/install-charmcraft).
+
+To run the charm locally with Juju, it is recommended to use [LXD](https://linuxcontainers.org/lxd/introduction/) as your virtual machine manager. Instructions for running Juju on LXD can be found [here](https://juju.is/docs/olm/lxd).
+
+## Build and Deploy
+
+To build the charm in this repository, from the root of the dir you can run:
+Once you have Juju set up locally, to download, build and deploy the charm you can run:
+
+### Deploy
+
+```bash
+# Clone and enter the repository
+git clone https://github.com/canonical/kafka-operator.git
+cd kafka-operator/
+
+# Create a working model
+juju add-model kafka
+
+# Enable DEBUG logging for the model
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+
+# Build the charm locally
+charmcraft pack
+
+# Deploy the latest ZooKeeper release
+juju deploy zookeeper --channel edge -n 3
+
+# Deploy the charm
+juju deploy ./*.charm -n 3
+
+# After ZooKeeper has initialised, relate the applications
+juju relate kafka zookeeper
+```
+
+## Developing
+
+You can use the environments created by `tox` for development:
+
+```shell
+tox --notest -e unit
+source .tox/unit/bin/activate
+```
+
+### Testing
+
+```shell
+tox -e fmt           # update your code according to linting rules
+tox -e lint          # code style
+tox -e unit          # unit tests
+tox -e integration   # integration tests
+tox                  # runs 'lint' and 'unit' environments
+```
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to the Charmed Kafka Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.

README.md

@@ -1,26 +1,43 @@
-# operator-template
+## Kafka Operator - a Charmed Operator for running Apache Kafka from Canonical
 
-## Description
+This repository hosts the Machine Python Operator for [Apache Kafka](https://kafka.apache.org).
+The Kafka Operator is a Python script that uses the latest upstream Kafka binaries released by the The Apache Software Foundation that comes with Kafka, made available using the [Kafka Snap](https://snapcraft.io/kafka) distributed by Canonical.
 
-TODO: Describe your charm in a few paragraphs of Markdown
+As currently Kafka requires a paired ZooKeeper deployment in production, this operator makes use of the [ZooKeeper Operator](https://github.com/canonical/zookeeper-operator) for various essential functions. 
 
-## Usage
+### Usage
+
+The Kafka and ZooKeeper operators can both be deployed and connected to each other using the Juju command line as follows:
 
-TODO: Provide high-level usage, such as required config or relations
+```bash
+$ juju deploy zookeeper -n 3
+$ juju deploy kafka -n 3
+$ juju relate kafka zookeeper
+```
 
-## Relations
+## A fast and fault-tolerant, real-time event streaming platform!
 
-TODO: Provide any relations which are provided or required by your charm
+Manual, Day 2 operations for deploying and operating Apache Kafka, topic creation, client authentication, ACL management and more are all handled automatically using the [Juju Operator Lifecycle Manager](https://juju.is/docs/olm).
 
-## OCI Images
+### Key Features
+- SASL/SCRAM auth for Broker-Broker and Client-Broker authenticaion enabled by default.
+- Access control management supported with user-provided ACL lists.
+- Fault-tolerance, replication and high-availability out-of-the-box.
+- Streamlined topic-creation through [Juju Actions](https://juju.is/docs/olm/working-with-actions) and [application relations](https://juju.is/docs/olm/relations)
 
-TODO: Include a link to the default image your charm uses
 
-## Contributing
+### Checklist
 
-<!-- TEMPLATE-TODO: Change this URL to be the full Github path to CONTRIBUTING.md-->
+- [x] Super-user creation
+- [x] Inter-broker auth
+- [x] Horizontally scale brokers
+- [x] Username/Password creation for related applications
+- [ ] Automatic topic creation with associated user ACLs
+- [ ] Partition rebalancing during broker scaling
+- [ ] Rack awareness support
+- [ ] Persistent storage support with [Juju Storage](https://juju.is/docs/olm/defining-and-using-persistent-storage)
+- [ ] TLS/SSL support
+
+## Usage
 
-Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhancements to this
-charm following best practice guidelines, and
-[CONTRIBUTING.md](https://github.com/<name>/<operator>/blob/main/CONTRIBUTING.md) for developer
-guidance.
+This charm is still in active development. If you would like to contribute, please refer to [CONTRIBUTING.md](https://github.com/canonical/kafka-operator/blob/main/CONTRIBUTING.md)