chore(docs): update contributing guidelines (charmkeeper)

.github/pull_request_template.md

@@ -0,0 +1,29 @@
+#### What this PR does
+
+#### Why we need it
+
+#### Checklist
+
+- [ ] I followed the [contributing guide](https://github.com/canonical/is-charms-contributing-guide)
+- [ ] I added or updated the documentation (if applicable)
+- [ ] I updated `docs/changelog.md` with user-relevant changes
+- [ ] I added a [change artifact](../docs/release-notes/template/docs/release-notes/template/_change-artifact-template.yaml) for user-relevant changes in `docs/release-notes/artifacts`. If no change artifact is necessary, I tagged the PR with the label `no-release-note`.
+- [ ] I used AI to assist with preparing this PR
+- [ ] I added or updated tests as needed (unit and integration)
+- [ ] **If integration test modules are used:** I updated the workflow configuration  
+      (e.g., in `.github/workflows/integration_tests.yaml`, ensure the `modules` list is correct)
+- [ ] **If this is a Grafana dashboard:** I added a screenshot of the dashboard
+- [ ] **If this is Terraform:** `terraform fmt` passes and `tflint` reports no errors
+- [ ] **If this is Rockcraft:** I updated the version
+
+<!--  
+You can adjust the checklist to match the project.
+
+If you are an AI assistant (e.g., GitHub Copilot, ChatGPT, Claude), follow these instructions when generating or completing PR descriptions:
+
+1. Add a **Test plan** section explaining how the changes were tested, including any manual, unit, integration, or workflow tests.
+2. Add a **Review focus** section highlighting tricky parts, important decisions, or areas needing human attention.
+3. Identify and document any **potential breaking changes**.
+4. Highlight any **new dependencies, APIs, modules, or workflow changes** introduced by this PR.
+-->
+

CONTRIBUTING.md

@@ -1,15 +1,15 @@
-# How to contribute
+# Contributing
 
-This document explains the processes and practices recommended for contributing enhancements to the `content-cache` charms.
+This document explains the processes and practices recommended for contributing enhancements to the Content Cache Operator.
 
 ## Overview
 
-- Generally, before developing enhancements to these charms, you should consider [opening an issue
+- Generally, before developing enhancements to this charm, you should consider [opening an issue
   ](https://github.com/canonical/content-cache-operator/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 [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
   or [Discourse](https://discourse.charmhub.io/).
-- Familiarizing yourself with the [Juju documentation](https://documentation.ubuntu.com/juju/latest/howto/manage-charms/index.html)
+- Familiarizing yourself with the [Juju documentation](https://documentation.ubuntu.com/juju/3.6/howto/manage-charms/)
   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
@@ -25,10 +25,11 @@ This document explains the processes and practices recommended for contributing
 When contributing, you must abide by the
 [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
 
-## Releases and versions
+## Changelog
 
 Please ensure that any new feature, fix, or significant change is documented by
-adding an entry to the [CHANGELOG.md](https://github.com/canonical/content-cache-operator/blob/main/CHANGELOG.md) file.
+adding an entry to the [CHANGELOG.md](docs/changelog.md) file. Use the date of the
+contribution as the header for new entries.
 
 To learn more about changelog best practices, visit [Keep a Changelog](https://keepachangelog.com/).
 
@@ -39,7 +40,7 @@ notify in advance the people involved to avoid confusion;
 also, reference the issue or bug number when you submit the changes.
 
 - [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
-  our [GitHub repository](https://github.com/canonical/content-cache-operator/)
+  our [GitHub repository](https://github.com/canonical/content-cache-operator)
   and add the changes to your fork, properly structuring your commits,
   providing detailed commit messages and signing your commits.
 - Make sure the updated project builds and runs without warnings or errors;
@@ -49,35 +50,31 @@ also, reference the issue or bug number when you submit the changes.
 
 Your changes will be reviewed in due time; if approved, they will be eventually merged.
 
-### Describing pull requests
+### AI
 
-To be properly considered, reviewed and merged,
-your pull request must provide the following details:
+You are free to use any tools you want while preparing your contribution, including
+AI, provided that you do so lawfully and ethically.
 
-- **Title**: Summarize the change in a short, descriptive title.
+Avoid using AI to complete issues tagged with the "good first issues" label. The
+purpose of these issues is to provide newcomers with opportunities to contribute
+to our projects and gain coding skills. Using AI to complete these tasks
+undermines their purpose.
 
-- **Overview**: Describe the problem that your pull request solves.
-  Mention any new features, bug fixes or refactoring.
+We have created instructions and tools that you can provide AI while preparing your contribution: [`copilot-collections`](https://github.com/canonical/copilot-collections)
 
-- **Rationale**: Explain why the change is needed.
+While it isn't necessary to use `copilot-collections` while preparing your
+contribution, these files contain details about our quality standards and
+practices that will help the AI avoid common pitfalls when interacting with
+our projects. By using these tools, you can avoid longer review times and nitpicks.
 
-- **Juju Events Changes**: Describe any changes made to Juju events, or
-  "None" if the pull request does not change any Juju events.
+If you choose to use AI, please disclose this information to us by indicating
+AI usage in the PR description (for instance, marking the checklist item about
+AI usage). You don't need to go into explicit details about how and where you used AI.
 
-- **Module Changes**: Describe any changes made to the module, or "None"
-  if your pull request does not change the module.
-
-- **Library Changes**: Describe any changes made to the library,
-  or "None" is the library is not affected.
-
-- **Checklist**: Complete the following items:
-
-  - The [charm style guide](https://juju.is/docs/sdk/styleguide) was applied
-  - The [contributing guide](https://github.com/canonical/is-charms-contributing-guide) was applied
-  - The changes are compliant with [ISD054 - Managing Charm Complexity](https://discourse.charmhub.io/t/specification-isd014-managing-charm-complexity/11619)
-  - The documentation is updated
-  - The PR is tagged with appropriate label (trivial, senior-review-required)
-  - The changelog has been updated
+Avoid submitting contributions that you don't fully understand.
+You are responsible for the entire contribution, including the AI-assisted portions.
+You must be willing to engage in discussion and respond to any questions, comments,
+or suggestions we may have. 
 
 ### Signing commits
 
@@ -87,7 +84,7 @@ we use the [Canonical contributor license agreement](https://assets.ubuntu.com/v
 
 #### Canonical contributor agreement
 
-Canonical welcomes contributions to the Discourse charm. Please check out our
+Canonical welcomes contributions to the Content Cache Operator. Please check out our
 [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.
 
 The CLA sign-off is simple line at the
@@ -102,7 +99,87 @@ To add signatures on your commits, follow the
 
 ## Develop
 
-Please refer to the charm specific guides:
+To make contributions to this charm, you'll need a working
+[development setup](https://documentation.ubuntu.com/juju/latest/howto/manage-your-juju-deployment/set-up-your-juju-deployment-local-testing-and-development/).
+
+The code for this charm can be downloaded as follows:
+
+```
+git clone https://github.com/canonical/content-cache-operator
+```
+
+Make sure to install [`uv`](https://docs.astral.sh/uv/). For example, you can install `uv` on Ubuntu using:
+
+```bash
+sudo snap install astral-uv --classic
+```
+
+For other systems, follow the [`uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+Then install `tox` with its extensions, and install a range of Python versions:
+
+```bash
+uv python install
+uv tool install tox --with tox-uv
+uv tool update-shell
+```
+
+To create a development environment, run:
+
+```bash
+uv sync --all-groups
+source .venv/bin/activate
+```
+
+### Test
+
+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``: Executes all of the basic checks and tests (``lint``, ``unit``, ``static``, and ``coverage-report``).
+* ``tox -e fmt``: Runs formatting using ``ruff``.
+* ``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.
+
+### Build the rock and charm
+
+Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/stable/) to create an
+OCI image for the Content Cache app, and then upload the image to a MicroK8s registry,
+which stores OCI archives so they can be downloaded and deployed.
+
+Enable the MicroK8s registry:
+
+```bash
+microk8s enable registry
+```
+
+The following commands pack the OCI image and push it into
+the MicroK8s registry:
+
+```bash
+cd <project_dir>
+rockcraft pack
+skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:<rock-name>.rock docker://localhost:32000/<app-name>:latest
+```
+
+Build the charm in this git repository using:
+
+```shell
+charmcraft pack
+```
+
+### Deploy
+
+```bash
+# Create a model
+juju add-model charm-dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+# Deploy the charm
+juju deploy ./content-cache*.charm 
+```
+
+
 
-- [content-cache/CONTRIBUTING.md](content-cache/CONTRIBUTING.md)
-- [content-cache-backend-configs/CONTRIBUTING.md](content-cache-backends-config/CONTRIBUTING.md)

docs/changelog.md

@@ -0,0 +1,9 @@
+(changelog)=
+
+# Changelog
+
+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.1.0/).
+
+Each revision is versioned by the date of the revision.