Merge pull request #20 from canonical/contributing-guide-changes

Update contributing guide

CONTRIBUTING.md

@@ -1,15 +1,65 @@
+<!-- Remember to update this file for your charm -- replace <charm-name> with the appropriate name. -->
+
 # Contributing
 
+## Overview
+
+This document explains the processes and practices recommended for contributing enhancements to the <charm-name> charm.
+
+- Generally, before developing enhancements to this charm, you should consider [opening an issue
+  ](link to issues page) explaining your use case.
+- If you would like to chat with us about your use-cases or proposed implementation, you can reach
+  us at [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+  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 operators of 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.
+- Please generate src documentation for every commit. See the section below for more details.
+
+## Developing
+
 To make contributions to this charm, you'll need a working [development setup](https://juju.is/docs/sdk/dev-setup).
 
+The code for this charm can be downloaded as follows:
+
+```
+git clone https://github.com/canonical/<charm-name>
+```
+
+You can use the environments created by `tox` for development:
+
+```shell
+tox --notest -e unit
+source .tox/unit/bin/activate
+```
+
+<!-- TODO: Check whether these instructions are more appropriate:
 You can create an environment for development with `tox`:
 
 ```shell
 tox devenv -e integration
 source venv/bin/activate
 ```
+-->
+
+### Testing
 
-## Generating src docs for every commit
+This project uses `tox` for managing test environments. There are some pre-configured environments
+that can be used for linting and formatting code when you're preparing contributions to the charm:
+
+* `tox`: Runs all of the basic checks (`lint`, `unit`, `static`, and `coverage-report`).
+* `tox -e fmt`: Runs formatting using `black` and `isort`.
+* `tox -e lint`: Runs a range of static code analysis to check the code.
+* `tox -e static`: Runs other checks such as `bandit` for security issues.
+* `tox -e unit`: Runs the unit tests.
+* `tox -e integration`: Runs the integration tests.
+
+### Generating src docs for every commit
 
 Run the following command:
 
@@ -18,25 +68,43 @@ echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit
 chmod +x .git/hooks/pre-commit
 ```
 
-## Testing
+### Building the charm
 
-This project uses `tox` for managing test environments. There are some pre-configured environments
-that can be used for linting and formatting code when you're preparing contributions to the charm:
+Build the charm in this git repository using:
 
 ```shell
-tox run -e format        # update your code according to linting rules
-tox run -e lint          # code style
-tox run -e unit          # unit tests
-tox run -e integration   # integration tests
-tox                      # runs 'format', 'lint', and 'unit' environments
+charmcraft pack
 ```
 
-## Build the charm
+<!-- TODO: Determine if there is a generic way to write these instructions
+For the integration tests (and also to deploy the charm locally), the indico
+and indico-nginx images are required in the microk8s registry. To enable it:
 
-Build the charm in this git repository using:
+    microk8s enable registry
 
-```shell
-charmcraft pack
+The following commands import the images in the Docker daemon and push them into the registry:
+
+    cd [project_dir]/indico_rock && rockcraft pack rockcraft.yaml
+    skopeo --insecure-policy copy oci-archive:indico_1.0_amd64.rock docker-daemon:localhost:32000/indico:latest
+    docker push localhost:32000/indico:latest
+    cd [project_dir]/nginx_rock && rockcraft pack rockcraft.yaml
+    skopeo --insecure-policy copy oci-archive:indico_nginx_1.0_amd64.rock docker-daemon:localhost:32000/indico-nginx:latest
+    docker push localhost:32000/indico-nginx:latest
+-->
+
+### Deploying
+
+<!-- TODO: Determine if the juju deploy command should be updated -->
+
+```bash
+# Create a model
+juju add-model charm-dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+# Deploy the charm (assuming you're on amd64)
+juju deploy ./<charm-name>.charm 
 ```
 
-<!-- You may want to include any contribution/style guidelines in this document>
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to the <charm-name> charm. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.

docs-template/how-to/contribute.md

@@ -0,0 +1,5 @@
+# How to contribute
+
+<!-- TODO: Update the link to point to the correct repo!! -->
+
+See the [contributing guide](https://github.com/canonical/is-charms-template-repo/blob/main/CONTRIBUTING.md) on GitHub.

docs-template/index.md

@@ -1,17 +1,17 @@
-# < Charm name > Operator
+# <charm-name> Operator
 
 <!-- A single sentence that says what the product is, succinctly and memorably. Add a 1-2 sentence description of what the charm software does. -->
 
-A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing < Charm software > on 
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing <Charm software> on 
 Kubernetes. 
 
 <!-- A paragraph of 2-5 short sentences, that describes what the product does and what need the product meets. -->
 
 Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. 
-For < Charm name >, this includes:
+For <charm-name>, this includes:
 * list or summary of app-specific features
 
-The < Charm name > charm allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to 
+The <charm-name> charm allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to 
 [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings.
 
 <!-- Finally, a paragraph that describes whom the product is useful for. -->
@@ -39,15 +39,15 @@ If there's a particular area of documentation that you'd like to see that's miss
 
 ## Project and community
 
-The < Charm name > Operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community 
+The <charm-name> Operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community 
 projects, contributions, suggestions, fixes, and constructive feedback.
 
 - [Code of conduct](https://ubuntu.com/community/code-of-conduct)
 - [Get support](https://discourse.charmhub.io/)
 - [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
 - [Contribute](link to Contribute page)
 
-Thinking about using the < Charm > Operator for your next project? 
+Thinking about using the <charm-name> Operator for your next project? 
 [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
 
 # Contents