Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (70 loc) · 8.96 KB

CONTRIBUTING.md

File metadata and controls

105 lines (70 loc) · 8.96 KB
Raw

Contributing

Basics

Want to contribute? Awesome! Thank you!

All contributions must be licensed under GPLv2 (or a compatible license; see COPYING). If you don't specify a license, GPLv2 will be assumed.

How to Suggest New Features

Please create an issue first and wait for feedback before starting implementation. This prevents wasted effort on changes that might not be accepted.

How to Contribute Code Changes

Please fork the repository, implement your changes in a branch, and then submit a pull request (PR).

🧪 Testing & Verification

  • Unit Tests: We highly encourage including unit tests with your contributions. However, if your code was generated by an AI coding agent, unit tests are mandatory.

  • Integration Tests: Functional/integration tests—like those already in tests/can-actually-be-used—must be created for new features. If no integration test is feasible (e.g., the change is purely internal refactoring or documentation-only), explain why in the PR description.

  • Self-Verification: Before committing, run local tests and linters to verify your code. Do not commit failing tests. Run make test to execute the full test suite (unit tests + Python tests).

  • Note on Integration Tests: Tests in tests/can-actually-be-used use a virtual USB device via the dummy-hcd kernel module and must be run manually via tests/can-actually-be-used/run-tests.sh.

  • If dummy-hcd is not included in your kernel build, run tests/can-actually-be-used/setup-dummyhcd.sh first to build and install it as a DKMS module.

  • Platform Packaging: Packaging on all platforms (Ubuntu, Fedora, Arch) must succeed.

  • How to verify locally: Run make build-{debian,fedora,arch} (or make build-all) using Docker.

  • CI for Forks (Custom Runners): Because our default CI does not run automatically on forks, you must verify your changes locally (as mentioned above) or set up a custom GitHub Actions runner. Setting up a custom runner is easy and allows you to execute the full CI pipeline—including packaging tests—properly right in your own repository. Check out the guide in the wiki: Using the test suite when forking.

  • Security & Linting: DevSkim and other automated review warnings must be either resolved or marked as false positives with a provided explanation.

🛡️ Code Quality & Scope

  • Strict Scoping: Keep PRs strictly scoped to the requested feature or bug fix. Do not refactor unrelated code or change formatting outside the scope of the issue.
  • Dependencies: Do not introduce new external dependencies unless strictly necessary and explicitly approved. Prefer standard library solutions.
  • Security Changes: Any PR that touches security-relevant code must include a clear rationale for the change. Vague claims like "security improvements" without a logical explanation will not be accepted. (Note: Do not publicly disclose exact attack scenarios for unpatched vulnerabilities. Please refer to our security policy for responsible disclosure).

📝 Documentation

  • Keep it Updated: Changes that introduce new config options or troubleshooting steps should include updated documentation.

  • Manpages must be updated manually.

  • Other documentation is pulled from this repository's GitHub wiki via make update-other-docs (only run this when your branch has no uncommitted changes).

  • General Rule: If you think a feature could benefit from documentation → add it!

🔀 Git Workflow & PRs

  • Atomic Commits: Keep commits atomic. Do not bundle massive changes into a single commit; break them down logically.
  • Issue Linking: Every PR must reference the issue it addresses in the description (e.g., Closes #123 or Refs #123). If there is no ticket for it, please create one. If your PR is related to the ongoing security audit, feel free to reference issue #55.
  • Assignee: Assign the PR to yourself so it is clear who is responsible for it.
  • Reviewer: Add @mcdope as a reviewer to signal the PR is ready. PRs without a reviewer assigned are treated as Draft/WIP and will not be reviewed.
  • Labels: Add labels matching the type of change (e.g., bug, enhancement, documentation). If no exact label exists, use the closest match.
  • PR Descriptions (Reasoning): PR descriptions must include a brief summary of why a specific technical approach was chosen, unless the change is trivially self-explanatory.
  • PR Descriptions (Security): If your PR addresses a security concern, the description must clearly explain the intended security benefit without exposing users to risk. "This improves security" is not sufficient.

🤖 AI-Assisted Contributions

If you are using AI tools (e.g., Claude, Codex, Cursor, Aider) to write code for your PR, you must adhere to the following additional rules:

  • No Autonomous Bots: Fully automated agents that scrape issues and open PRs without human oversight are strictly forbidden. This includes automated bounty-hunting tools and services (e.g., TaskBounty) — these are never eligible for the security bounty, regardless of the quality of the submission. A human must review, understand, and take responsibility for every line of code submitted. Drive-by bot PRs will be marked as spam and closed immediately. GitHub account activity is reviewed as part of PR evaluation — accounts that show signs of automation or that were created specifically to submit PRs will not be accepted.
  • Commit Attribution: AI-assisted commits must include a Co-authored-by trailer at the very end of the commit message (e.g., Co-authored-by: NameOfAI <email@example.com>). Ensure there is a blank line separating the main message body from the trailer so Git and platforms like GitHub parse it correctly.
  • PR Descriptions (Tagging): Add a note in the PR description indicating that an AI coding agent assisted with the PR (e.g., 🤖 This PR was generated with the assistance of [AI Name]).
  • Proof of Execution: AI contributions must provide verifiable proof that all tests passed — unit tests (make test) and the full functional suite (tests/can-actually-be-used/run-tests.sh). Acceptable proof: a screenshot of a successful manual run, or a link to your own GitHub Actions CI job where all tests succeeded. Running only make test without the functional suite is not sufficient.
  • Zero Tolerance: If an AI-generated PR fails to fulfill ANY of the guidelines in this file, I will close it immediately. Human contributions (which are manually verified by me) are granted slightly more leniency when it comes to minor rule violations.
  • Human Verification: To prove a human is actually overseeing the submission and has read these guidelines, you must include the exact phrase I have read the rules at the very bottom of your PR description.

🍏 "I don't use Linux, so my AI / I can't handle PAM stuff locally"

Set up a VM. If you want to work on code for Linux, you need Linux for testing—it's as simple as that. You can also easily use the provided Docker definitions.

How to Contribute Documentation

The Wiki is editable by anyone—feel free to just jump in and work on it.

If you want to work on the manpages, note that these are managed in the code repository. Please see "How to Contribute Code Changes" above.

💰 Security Bounty

A bounty is available for qualifying security contributions. See issue #55 for the current bounty offer.

Your PR is not bounty-eligible if any of the following apply:

  • You failed to verify your own work and required the maintainer to do it for you.
  • You violated any point outlined in this document.
  • Your GitHub activity indicates a fully automated account, or the account was created specifically to submit this PR.
  • The PR was submitted by, or primarily authored by, an automated bounty-hunting tool or service (e.g., TaskBounty). Bounties exist to reward genuine contributor effort — not automated pipelines scraping issues for reward opportunities.
  • The contribution is considered trivial or low-impact:
    • Minor changes touching only a handful of lines.
    • Security fixes for vulnerabilities scoring below Critical on the CVSS scale. Exception: High-severity findings are eligible if they specifically apply to the deny_remote feature.

For any bounty claim you must provide a CVSS estimate; the maintainer will verify it before payout.

Genuine, verified effort that actively improves the codebase is rewarded. PRs that require the maintainer to act as a human linter will not be considered for the bounty.