Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
erinecon wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 28 additions & 32 deletions .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,29 @@
Applicable spec: <link>
#### 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.
-->

### Overview

<!-- A high level overview of the change -->

### Rationale

<!-- The reason the change is needed -->

### Juju Events Changes

<!-- Any changes to the juju events being observed (newly added, significantly modified or deleted) -->

### Module Changes

<!-- Any high level changes to modules and why (Service, Observer, helper) -->

### Library Changes

<!-- Any changes to charm libraries -->

### Checklist

- [ ] 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 for charmhub is updated.
- [ ] The PR is tagged with appropriate label (`urgent`, `trivial`, `complex`).
- [ ] The changelog is updated with changes that affects the users of the charm.
- [ ] The application version number is updated in `github-runner-manager/pyproject.toml`.

<!-- Explanation for any unchecked items above -->
197 changes: 157 additions & 40 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1,185 @@
# Contribute
# Contributing

This document explains the processes and practices recommended for contributing enhancements to the GitHub runner Operator.

## Overview

This document explains the processes and practices recommended for contributing enhancements to the GitHub Runner operator.
- Generally, before developing enhancements to this charm, 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 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/github-runner-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

Check failure on line 53 in CONTRIBUTING.md

View workflow job for this annotation

GitHub Actions / docs-checks / vale 

[vale] reported by reviewdog 🐶
[Canonical.007-Headings-sentence-case] 'AI' should use sentence-style capitalisation.

Raw Output:
{"message": "[Canonical.007-Headings-sentence-case] 'AI' should use sentence-style capitalisation.", "location": {"path": "CONTRIBUTING.md", "range": {"start": {"line": 53, "column": 5}}}, "severity": "ERROR"}

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 GitHub runner Operator. Please check out our
[contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.

* Generally, before developing enhancements to this charm, 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/).
* Familiarizing 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 administrators of this charm.
For more details, check our [contributing guide](https://github.com/canonical/is-charms-contributing-guide/blob/main/CONTRIBUTING.md).
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.

## Developing
#### Verified signatures on commits

For any problems with this charm, please [report bugs here](https://github.com/canonical/github-runner-operator/issues).
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:

```shell
git clone https://github.com/canonical/github-runner-operator.git
```
git clone https://github.com/canonical/github-runner-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
```

Prior to working on the charm ensure Juju is connected to an LXD cloud, see the [upstream documentation](https://documentation.ubuntu.com/juju/3.6/reference/cloud/list-of-supported-clouds/the-lxd-cloud-and-juju/) for details.
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 two `tox` working directories,
one in the root directory and one in the directory `github-runner-manager` for
the Python library. For each `tox` working directory, there are some pre-configured environments
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.
* ``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

> NOTE: Integration tests are currently intended to run on the CI and may not work locally without further argument.
Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/stable/) to create an
OCI image for the GitHub runner app, and then upload the image to a MicroK8s registry,
which stores OCI archives so they can be downloaded and deployed.

<!-- vale Canonical.007-Headings-sentence-case = NO -->
#### CI testing setup guidelines
<!-- vale Canonical.007-Headings-sentence-case = YES -->
Enable the MicroK8s registry:

```bash
microk8s enable registry
```

To prefer explicit setting arguments passing, use `extra-arguments` of the
[following reusable workflow](https://github.com/canonical/operator-workflows/blob/main/.github/workflows/integration_test_run.yaml)
to pass in non-sensitive values.
For sensitive values (`INTEGRATION_TOKEN`: `--token`, `OS_PASSWORD`: `--openstack-password`), map
them through `INTEGRATION_TEST_SECRET_ENV_NAME_<N>`
environment variable settings under [repository](https://github.com/canonical/github-runner-operator)
> settings > variables > actions.
This is to prevent GitHub from leaking secrets when passing them over the CLI calls (unresolved).
The following commands pack the OCI image and push it into
the MicroK8s registry:

### Building the charm
```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
```

## Canonical contributor agreement
### 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 ./github-runner*.charm
```



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.
Loading