chore(docs): update contributing guidelines (charmkeeper) (#170)

erinecon · Copilot · web-flow · commit 76bac252da24 · 2026-04-22T11:26:25.000-04:00
* chore(docs): update contributing guidelines (charmkeeper)

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;

* fix(docs): build errors

* chore: clarify PR checklist and remove unnecessary item

* chore(docs): revert changes in CONTRIBUTING.md

* fix(docs): whoops we're ignoring the changelog

* fix: update pr checklist to incorporate previous items, remove duplicate items

---------

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,15 +1,29 @@
-### Overview
+#### What this PR does
 
-<!-- A high level overview of the change -->
+#### Why we need it
 
-### Rationale
-
-<!-- The reason the change is needed -->
-
-### Checklist
+#### Checklist
 
 - [ ] Changes comply with the project's coding standards and guidelines (see CONTRIBUTING.md and STYLE.md)
 - [ ] `CONTRIBUTING.md` has been updated upon changes to the contribution/development process (e.g. changes to the way tests are run)
 - [ ] Technical author has been assigned to review the PR in case of documentation changes (usually *.md files)
+- [ ] I updated `docs/changelog.md` with user-relevant changes
+- [ ] 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 PR involves a Grafana dashboard:** I added a screenshot of the dashboard
+- [ ] **If this PR involves Terraform:** `terraform fmt` passes and `tflint` reports no errors
+- [ ] **If this PR involves 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.
+-->
 
-<!-- Explanation for any unchecked items above -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,9 +1,9 @@
-# Contribute
-
-## Overview
+# Contributing
 
 This document explains the processes and practices recommended for contributing enhancements to the codebase.
 
+## Overview
+
 - Generally, before developing enhancements to this code base, you should consider [opening an issue](https://github.com/canonical/github-runner-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 Charm Development Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) or [Discourse](https://discourse.charmhub.io/).
 - All enhancements require review before being merged. Code review typically examines
@@ -15,6 +15,14 @@ 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).
 
+## 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,
@@ -32,31 +40,46 @@ 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.
 
-- **Checklist**: Complete the following items:
+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.
 
-  - The PR is tagged with appropriate label (`urgent`, `trivial`, `senior-review-required`, `documentation`).
+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 contributor agreement
+
+Canonical welcomes contributions to the GitHub runner Operator. Please check out our
+[contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.
 
-Canonical welcomes contributions to this repository. 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
 
@@ -87,7 +110,6 @@ We like to follow idomatic Go practices and community standards when writing Go
 We have added an instruction file `go.instructions.md` in `.github/instructions.md` that is used by GitHub Copilot to help you write code that follows these practices.
 We have added a [Style Guide](./STYLE.md) that you can refer to for more details.
 
-
 ### Test
 
 This project uses standard Go testing tools for unit tests and integration tests.
@@ -169,8 +191,6 @@ Higher complexity leads to code that is harder to read, understand, test and mai
 There are exceptions where higher complexity is justified (e.g., validation, initialization),
 but those should require explicit justification using `nolint` directives.
 
-
-
 ### Charm development
 
 The charm uses the [12 factor app pattern](https://canonical-12-factor-app-support.readthedocs-hosted.com/latest/).
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,7 +1,13 @@
+(changelog)=
+
 # Changelog
 
 This changelog documents user-relevant changes to the Planner charm and Webhook gateway charm.
 
+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.
+
 ## 2026-04-13
 
 - add 5xx error logging to planner routes.
diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst
@@ -0,0 +1,63 @@
+.. meta::
+   :description: Familiarize yourself with contributing to the GitHub runner charms documentation.
+
+.. _how_to_contribute:
+
+How to contribute
+=================
+
+.. note::
+
+   See `CONTRIBUTING.md <https://github.com/canonical/github-runner-operators/blob/main/CONTRIBUTING.md>`_
+   for information on contributing to the source code. 
+
+Our documentation is hosted on `Read the Docs <https://documentation.ubuntu.com/github-runner-operators>`_ 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/github-runner-operators>`_.
+You may open a pull request with your documentation changes, or you can
+`file a bug <https://github.com/canonical/github-runner-operators/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>`_.
+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. 
+
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
@@ -1,2 +1,9 @@
 How-to guides
 =============
+
+The following guides cover key processes and common tasks for managing and using the GitHub runner charms.
+
+.. toctree::
+   :maxdepth: 1
+
+   Contribute <contribute>
