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,50 +1,185 @@
 # Contributing
 
-To make contributions to this charm, you'll need a working [development setup](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-juju-deployment/set-up-your-juju-deployment-local-testing-and-development/).
+This document explains the processes and practices recommended for contributing enhancements to the HAProxy Operator.
 
-You can create an environment for development with `tox`:
+## Overview
 
-```shell
-tox devenv -e integration
-source venv/bin/activate
+- Generally, before developing enhancements to this charm, you should consider [opening an issue
+  ](https://github.com/canonical/haproxy-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/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
+  - test coverage
+  - user experience for Juju operators of this charm.
+- Once your pull request is approved, we squash and merge your pull request branch onto
+  the `main` branch. This creates a linear Git commit history.
+- For further information on contributing, please refer to our
+  [Contributing Guide](https://github.com/canonical/is-charms-contributing-guide).
+
+## Code of conduct
+
+When contributing, you must abide by the
+[Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
+
+## Changelog
+
+Please ensure that any new feature, fix, or significant change is documented by
+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/).
+
+## Submissions
+
+If you want to address an issue or a bug in this project,
+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/haproxy-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;
+  this includes linting, documentation, code and tests.
+- Submit the changes as a
+  [pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+
+Your changes will be reviewed in due time; if approved, they will be eventually merged.
+
+### AI
+
+You are free to use any tools you want while preparing your contribution, including
+AI, provided that you do so lawfully and ethically.
+
+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.
+
+We have created instructions and tools that you can provide AI while preparing your contribution: [`copilot-collections`](https://github.com/canonical/copilot-collections)
+
+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.
+
+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.
+
+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
+
+To improve contribution tracking,
+we use the [Canonical contributor license agreement](https://assets.ubuntu.com/v1/ff2478d1-Canonical-HA-CLA-ANY-I_v1.2.pdf)
+(CLA) as a legal sign-off, and we require all commits to have verified signatures.
+
+#### Canonical contributor agreement
+
+Canonical welcomes contributions to the HAProxy 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
+end of the commit message certifying that you wrote it
+or have the right to commit it as an open-source contribution.
+
+#### Verified signatures on commits
+
+All commits in a pull request must have cryptographic (verified) signatures.
+To add signatures on your commits, follow the
+[GitHub documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+## Develop
+
+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/haproxy-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
 ```
 
-## Testing
+### 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:
 
-```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
-```
+* ``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 charm
+### Build the rock and charm
 
-Build the charm in this git repository using:
+Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/stable/) to create an
+OCI image for the HAProxy app, and then upload the image to a MicroK8s registry,
+which stores OCI archives so they can be downloaded and deployed.
 
-```shell
-charmcraft pack
+Enable the MicroK8s registry:
+
+```bash
+microk8s enable registry
 ```
 
-## Release the charm
+The following commands pack the OCI image and push it into
+the MicroK8s registry:
 
-Our release note policy is described in our [documentation](https://documentation.ubuntu.com/haproxy-charm/latest/release-notes/).
+```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
+```
 
-It is implemented by this [workflow](https://github.com/canonical/haproxy-operator/deployments/charmhub-stable-promote) that is triggered automatically on Monday.
+Build the charm in this git repository using:
 
-To give the required approval, click on the three horizontal dots on the right of the screen.
+```shell
+charmcraft pack
+```
 
-- Once the charm has been published to `stable`:
+### Deploy
 
-  - Create a PR to list the content for the [release note](https://github.com/canonical/haproxy-operator/tree/main/docs/release-notes/releases).
-  - Include all PR merged into the release published to stable and not listed in the previous release.
+```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 ./haproxy*.charm 
+```
 
-- Once merged, a new [Add release notes](https://github.com/canonical/haproxy-operator/pulls) PR will be automatically created.
 
-  - Edit it to refine the release notes.
 
-- Once merged, announce the new release on [Charmhub](https://discourse.charmhub.io/c/announcements-and-community/33) (tags: "charms" and "haproxy").

docs/how-to/contribute.rst

@@ -0,0 +1,67 @@
+.. meta::
+   :description: Familiarize yourself with contributing to the HAProxy charm documentation.
+
+.. _how_to_contribute:
+
+How to contribute
+=================
+
+.. note::
+
+   See `CONTRIBUTING.md <https://github.com/canonical/haproxy-operator/blob/main/CONTRIBUTING.md>`_
+   for information on contributing to the source code. 
+
+Our documentation is hosted on `Read the Docs <https://canonical-starter-pack.readthedocs-hosted.com>`_ to enable collaboration.
+Please use the links on each documentation page to either
+directly change something you see that's wrong, ask a question, or make a suggestion
+about a potential change.
+
+Our documentation is also available alongside the
+`source code on GitHub <https://github.com/canonical/haproxy-operator>`_.
+You may open a pull request with your documentation changes, or you can
+`file a bug <https://github.com/canonical/haproxy-operator/issues>`_
+to provide constructive feedback or suggestions.
+
+AI usage
+--------
+
+You are free to use any tools you want while preparing your contribution, including
+AI, provided that you do so lawfully and ethically. 
+
+Avoid using AI to complete
+`Canonical Open Documentation Academy issues <https://github.com/canonical/open-documentation-academy/issues>`_.
+The purpose of these issues is to provide newcomers with opportunities to
+contribute to our projects and gain documentation skills. Using AI to
+complete these tasks undermines their purpose.
+
+If you use AI to help with your PRs, be mindful. Avoid submitting contributions
+with entirely AI-generated documentation. The human aspect of documentation is
+important to us, and that includes tone, syntax, perspectives, and the
+occasional typo. 
+
+Some examples of valid AI assistance includes:
+
+* Checking for spelling or grammar errors
+* Drafting plans or outlines
+* Checking that your contribution aligns with the Canonical style guide
+
+We have created instructions and tools that you can provide AI while preparing
+your contribution in `copilot-collections <https://github.com/canonical/copilot-collections>`_: 
+
+* `Documentation instructions <https://github.com/canonical/copilot-collections/tree/main/assets/instructions/documentation>`_
+* `Documentation skills <https://github.com/canonical/copilot-collections/tree/main/assets/skills>`_
+
+While it isn't necessary to use ``copilot-collections`` while preparing your
+contribution, these files contain details about our documentation 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.
+
+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.
+
+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. 
+