From df1e1d18001d036a4857a504c8df93160d0eaa14 Mon Sep 17 00:00:00 2001 From: Javier Tia Date: Thu, 19 Nov 2026 11:59:18 -0600 Subject: [PATCH] CONTRIBUTING: Add a contributing guide The template had no contributing guide, and every repository created from it inherits the gap. A contributor to an extension repo had to read the workflows to learn how to test locally, what the pull request check does and how a tag becomes a release. Document the local test commands, the Test and Release workflows, the tag rules including the manual-run caveat, the changelog convention, the security route from the organization policy, and the Apache-2.0 contribution term. The text speaks of "this repository" so it stays correct in a derived repo. --- CONTRIBUTING.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d5488c6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# Contributing + +This guide is for anyone who wants to fix or improve the Avocado extension in this repository. + +## Where to start + +- Report a bug or propose a change in this repository's GitHub issues. +- Ask questions on [Discord](https://www.peridio.com/join-our-discord). + +## Test a change locally + +Run these commands from the repository root, where `avocado.yaml` lives. Replace `avocado-ext-` with the extension key in `avocado.yaml`. Replace `qemux86-64` with the `target` of a row in `.github/workflows/test.yml`. + +```sh +export AVOCADO_DISTRO_RELEASE=2024 AVOCADO_DISTRO_CHANNEL=next +avocado sdk install --target qemux86-64 +avocado ext install avocado-ext- --target qemux86-64 +avocado ext build avocado-ext- --target qemux86-64 +``` + +The two variables select the package feed and the SDK image tag. Set them to the `distro-release` and `distro-channel` of the same matrix row. + +## Pull request checks + +The Test workflow in `.github/workflows/test.yml` runs on every pull request. It calls `extension-test.yml` from `avocado-linux/actions@v1` once per matrix row. Each row installs the avocado CLI and runs `avocado sdk install`, `avocado ext install` and `avocado ext build` for that row's target and feed. The check builds the extension and never packages or publishes it. + +## Releases + +You cut a release by pushing a tag equal to the `version` in `avocado.yaml`, for example `git push origin 0.1.0`. Use a bare version shaped `X.Y.Z` or `X.Y.Z-*`. A tag with a `v` prefix does not start the Release workflow. + +The Release workflow packages the extension and publishes it to the feed of each matrix row in `.github/workflows/release.yml`. It fails the publish if the tag does not equal the `avocado.yaml` version. The workflow can also be run by hand from the Actions tab. A manual run on a branch skips the tag check and publishes whatever version `avocado.yaml` holds. + +## Changelog + +Record notable changes in `CHANGELOG.md`. The file follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Security issues + +Do not report a security vulnerability in a public issue, pull request or Discord. Report it privately as the [Avocado security policy](https://github.com/avocado-linux/avocado-cli/blob/main/SECURITY.md) describes. Use **Report a vulnerability** on the avocado-cli Security tab, or email info@peridio.com. Name the affected repository in your report. + +## License + +This repository is licensed under the Apache License 2.0. See the repository's LICENSE file. + +Section 5 of the license covers contributions. Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion is under the terms of the Apache License 2.0, without any additional terms or conditions.