diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..ccc1e4d82 --- /dev/null +++ b/.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 + + + diff --git a/.github/pull_request_template.yaml b/.github/pull_request_template.yaml deleted file mode 100644 index c3352de13..000000000 --- a/.github/pull_request_template.yaml +++ /dev/null @@ -1,33 +0,0 @@ -Applicable spec: - -### Overview - - - -### Rationale - - - -### Juju Events Changes - - - -### Module Changes - - - -### Library Changes - - - -### 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 is updated -- [ ] A [change artifact](https://github.com/canonical/haproxy-operator/blob/main/docs/release-notes/template/_change-artifact-template.yaml) was added for user-relevant changes in `docs/release-notes/artifacts`. If this PR does not require a change artifact, the PR has been tagged with `no-release-note`. -- [ ] The PR is tagged with appropriate label (`urgent`, `trivial`, `complex`) -- [ ] The [changelog](../docs/changelog.md) is updated with user-relevant changes in the format of [keep a changelog v1.1.0](https://keepachangelog.com/en/1.1.0/) - - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1e37e4ba..781ab15a0 100644 --- a/CONTRIBUTING.md +++ b/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 +rockcraft pack +skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:.rock docker://localhost:32000/: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="=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"). diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md deleted file mode 100644 index 2f20f5daa..000000000 --- a/docs/how-to/contribute.md +++ /dev/null @@ -1,45 +0,0 @@ -(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 stored in the `docs` directory alongside the [source code on GitHub](https://github.com/canonical/haproxy-operator/). -It is based on the Canonical starter pack -and hosted on [Read the Docs](https://about.readthedocs.com/). In structuring, -the documentation employs the [Diátaxis](https://diataxis.fr/) approach. - -Click on the "Contribute to this page" icon at the top of each page to propose changes. This button -will bring you directly to the source on GitHub. Similarly, you may click on "Give feedback" to provide -suggestions or feedback about any page in the documentation. - -On GitHub, 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. - -For syntax help and guidelines, -refer to the -{ref}`Canonical MyST style guide `. - -To run the documentation locally before submitting your changes: - -```bash -cd docs -make run -``` - -## Automatic checks - -GitHub runs automatic checks on the documentation -to verify spelling, validate links and style guide compliance. - -You can (and should) run the same checks locally: - -```bash -make spelling -make linkcheck -make vale -make lint-md -``` diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst new file mode 100644 index 000000000..fd48b2d11 --- /dev/null +++ b/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 `_ + for information on contributing to the source code. + +Our documentation is hosted on `Read the Docs `_ 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 `_. +You may open a pull request with your documentation changes, or you can +`file a bug `_ +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 `_. +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 `_: + +* `Documentation instructions `_ +* `Documentation 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. +