Contributing files (#310)

* Contributing files * Upper case names
canonical · Oct 4, 2023 · 36dd122 · 36dd122
1 parent 7fa2468
commit 36dd122
Show file tree

Hide file tree

Showing 2 changed files with 150 additions and 0 deletions.
diff --git a/charms/jupyter-controller/CONTRIBUTING.md b/charms/jupyter-controller/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing
+
+## Overview
+
+This document outlines the processes and practices recommended for contributing enhancements to `jupyter_controller`.
+
+## Talk to us First
+
+Before developing enhancements to this charm, you should [open an issue](/../../issues) explaining your use case. If you would like to chat with us about your use-cases or proposed implementation, you can reach us at [MLOps Mattermost public channel](https://chat.charmhub.io/charmhub/channels/mlops-documentation) or on [Discourse](https://discourse.charmhub.io/).
+
+## Pull Requests
+
+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.
+
+All pull requests require review before being merged. Code review typically examines:
+  - code quality
+  - test coverage
+  - user experience for Juju administrators of this charm.
+
+## Recommended Knowledge
+
+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.
+
+## Build Charm
+
+To build `jupyter_controller` run:
+
+```shell
+charmcraft pack
+```
+
+## Developing
+
+You can use the environments created by `tox` for development. For example, to load the `lint` environment into your shell, run:
+
+```shell
+tox --notest -e lint
+source .tox/lint/bin/activate
+```
+
+### Testing
+
+Use tox for testing. For example to test test, run:
+
+```shell
+tox -e test
+```
+
+See `tox.ini` for all available environments.
+
+### Deploy
+
+```bash
+# Create a model
+juju add-model dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+# Deploy the charm
+juju deploy ./jupyter_controller_ubuntu-20.04-amd64.charm \
+  --resource oci-image=$(yq '.resources."oci-image"."upstream-source"' metadata.yaml)
+```
+
+## Updating the charm for new versions of the workload
+
+To upgrade the source and resources of this charm, you must:
+
+1. Bump the `oci-image` in `metadata.yaml`
+1. Update the charm source for any changes, such as:
+    - YAML manifests in `src/` and/or any Kubernetes resource in `pod_spec`
+    - New or changed configurations passed to pebble workloads or through `pod.set_spec`
+1. Ensure integration and unit tests are passing; fix/adapt them otherwise
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to this charm. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing.
diff --git a/charms/jupyter-ui/CONTRIBUTING.md b/charms/jupyter-ui/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing
+
+## Overview
+
+This document outlines the processes and practices recommended for contributing enhancements to `jupyter_ui`.
+
+## Talk to us First
+
+Before developing enhancements to this charm, you should [open an issue](/../../issues) explaining your use case. If you would like to chat with us about your use-cases or proposed implementation, you can reach us at [MLOps Mattermost public channel](https://chat.charmhub.io/charmhub/channels/mlops-documentation) or on [Discourse](https://discourse.charmhub.io/).
+
+## Pull Requests
+
+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.
+
+All pull requests require review before being merged. Code review typically examines:
+  - code quality
+  - test coverage
+  - user experience for Juju administrators of this charm.
+
+## Recommended Knowledge
+
+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.
+
+## Build Charm
+
+To build `jupyter_ui` run:
+
+```shell
+charmcraft pack
+```
+
+## Developing
+
+You can use the environments created by `tox` for development. For example, to load the `lint` environment into your shell, run:
+
+```shell
+tox --notest -e lint
+source .tox/lint/bin/activate
+```
+
+### Testing
+
+Use tox for testing. For example to test test, run:
+
+```shell
+tox -e test
+```
+
+See `tox.ini` for all available environments.
+
+### Deploy
+
+```bash
+# Create a model
+juju add-model dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+# Deploy the charm
+juju deploy ./jupyter_ui_ubuntu-20.04-amd64.charm \
+  --resource oci-image=$(yq '.resources."oci-image"."upstream-source"' metadata.yaml)
+```
+
+## Updating the charm for new versions of the workload
+
+To upgrade the source and resources of this charm, you must:
+
+1. Bump the `oci-image` in `metadata.yaml`
+1. Update the charm source for any changes, such as:
+    - YAML manifests in `src/` and/or any Kubernetes resource in `pod_spec`
+    - New or changed configurations passed to pebble workloads or through `pod.set_spec`
+1. Ensure integration and unit tests are passing; fix/adapt them otherwise
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to this charm. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing.