Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
126 lines (92 loc) · 6 KB

CONTRIBUTING.md

File metadata and controls

126 lines (92 loc) · 6 KB
Raw

Contributing to qcom-linux-skills

Hi there! We’re thrilled that you’d like to contribute to this project. Your help is essential for keeping this project great and for making it better.

Branching Strategy

In general, contributors should develop on branches based off of main and pull requests should be made against main.

Proposing changes from an installed skill

If you installed the catalog with install.sh (the symlink default), every installed skill points back into your git clone — so when you or your coding agent improve a skill in place, the edit is already sitting on a branchable work tree. The qcom-skills-contribute skill (or its scripts/contribute.sh helper, directly) packages such an edit the way this document expects: it locates the clone, runs the catalog checks, creates a topic branch, and makes the DCO-signed commit with the trailers in the required order, stopping before push. Copy and marketplace installs are handled by a fallback that clones this repository fresh and transplants the modified skill. Either way, the result feeds into the pull-request flow below.

Submitting a pull request

  1. Please read our code of conduct and license.

  2. Fork and clone the repository.

    git clone https://github.com/<username>/qcom-linux-skills.git

  3. Create a new branch based on main:

    git checkout -b <my-branch-name> main

  4. Create an upstream remote to make it easier to keep your branches up-to-date:

    git remote add upstream https://github.com/qualcomm-linux/qcom-linux-skills.git

  5. Make your changes, add tests, and make sure the tests still pass.

  6. Commit your changes using the DCO. You can attest to the DCO by commiting with the -s or --signoff options or manually adding the "Signed-off-by":

    git commit -s -m "Really useful commit message"`

  7. After committing your changes on the topic branch, sync it with the upstream branch:

    git pull --rebase upstream main

  8. Push to your fork.

    git push -u origin <my-branch-name>

    The -u is shorthand for --set-upstream. This will set up the tracking reference so subsequent runs of git push or git pull can omit the remote and branch.

  9. Submit a pull request from your branch to main.

  10. Pat yourself on the back and wait for your pull request to be reviewed.

Copilot code review

Maintainers may request a review from GitHub Copilot on your pull request. Its comments are advisory only — Copilot never approves, requests changes, or blocks a merge — and its review behavior is governed by .github/copilot-instructions.md, which keeps it focused on concrete defects the CI checks cannot catch. Address the comments that point at real problems and feel free to say so when one does not.

Security Analysis of Pull Requests

To maintain the security and integrity of this project, all pull requests from external contributors are automatically scanned using Semgrep to detect insecure coding patterns and potential security flaws.

Static Analysis with Semgrep: We use Semgrep to perform lightweight, fast static analysis on every PR. This helps identify risky code patterns and logic flaws early in the development process.

Contributor Responsibility: If any issues are flagged, contributors are expected to resolve them before the PR can be merged.

Continuous Improvement: Our Semgrep ruleset evolves over time to reflect best practices and emerging security concerns.

By submitting a PR, you agree to participate in this process and help us keep the project secure for everyone.

Here are a few things you can do that will increase the likelihood of your pull request to be accepted:

  • Follow the existing style where possible: model new skills on the skill layout and conventions documented in the README (and the skills/qcom-device-info example), keep bash scripts shellcheck-clean with set -euo pipefail, follow PEP 8 for Python, and give every script an SPDX BSD-3-Clause-Clear license header.
  • Test your skill: run its scripts, and exercise the documented procedure end-to-end where hardware or a checkout of the target repository allows.
  • Keep your change as focused as possible. If you want to make multiple independent changes, please consider submitting them as separate pull requests.
  • Write a good commit message (see below).
  • It's a good idea to arrange a discussion with other developers to ensure there is consensus on large features, architecture changes, and other core code changes. PR reviews will go much faster when there are no surprises.

Commit messages

This project follows the same commit conventions as meta-qcom:

  • Each commit must be atomic — exactly one logical change — and the tree must remain functional after every commit.
  • The subject follows the form component: summary of the changes, where component identifies the skill or file being touched (for example skills/qcom-yocto-build-image: add sm8750-mtp machine).
  • The body first describes the problem being solved, so a reader understands why the change is needed, then uses the imperative mood to describe the actions taken. Prefer prose paragraphs wrapped at ~72 characters over bullet lists, and do not restate the diff.
  • Every commit carries a Signed-off-by trailer matching your git config identity (git commit -s).
  • If an AI coding assistant helped create the change, acknowledge it with an Assisted-by: AGENT_NAME:MODEL_VERSION trailer.