From aeb8065807e60a4e4b3f4c3f20eb9426488dbfe1 Mon Sep 17 00:00:00 2001 From: Christian Sass Date: Wed, 21 Oct 2026 13:46:29 -0500 Subject: [PATCH] docs: contribution terms, and a check that enforces them Vitals takes contributions under MIT, inbound equal to outbound, with a Developer Certificate of Origin instead of a CLA. That is the same shape Nextcloud uses on the project this tool was written to watch, so nobody contributing here is being asked for paperwork they would not sign upstream. tools/check-dco.sh verifies both presence and identity of the sign-off, and fails the pull request if either is wrong. Tested against three cases: unsigned, correctly signed, and signed by someone other than the author. Signed-off-by: Christian Sass --- .forgejo/workflows/dco.yml | 15 +++++++++ CONTRIBUTING.md | 68 ++++++++++++++++++++++++++++++++++++++ tools/check-dco.sh | 31 +++++++++++++++++ 3 files changed, 114 insertions(+) create mode 100644 .forgejo/workflows/dco.yml create mode 100644 CONTRIBUTING.md create mode 100755 tools/check-dco.sh diff --git a/.forgejo/workflows/dco.yml b/.forgejo/workflows/dco.yml new file mode 100644 index 0000000..6a0c233 --- /dev/null +++ b/.forgejo/workflows/dco.yml @@ -0,0 +1,15 @@ +name: DCO + +on: + pull_request: + branches: [main] + +jobs: + signoff: + runs-on: docker + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Every commit must be signed off + run: bash tools/check-dco.sh "origin/${{ github.base_ref }}..HEAD" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..22f789a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing to Vitals + +Thanks for looking. This is a small tool and the bar is simple: it must stay +readable, it must stay dependency-free, and it must not lie about what it +measures. + +## License of contributions + +Vitals is MIT licensed. Contributions are accepted under MIT, inbound equal to +outbound. There is no CLA to sign and no paperwork. + +You keep the copyright on what you write. You are licensing it to everyone under +MIT, which is the same thing everyone else already gets. + +## Sign your commits + +Every commit needs a `Signed-off-by` line. That is the Developer Certificate of +Origin: a one-line statement that you wrote the change, or have the right to +submit it, and that you are contributing it under this project's license. + +Git adds it for you: + +```bash +git commit -s -m "your message" +``` + +Which produces: + +``` +Signed-off-by: Your Name +``` + +A pull request whose commits lack the sign-off will fail the check. That is not +distrust, it is provenance: it is what protects the project if a contribution +later turns out to belong to someone's employer. + +**If you contribute as part of your job**, confirm with your employer first. The +sign-off asserts you have that permission. + +## What gets merged + +- Fixes with a reproduction. A bug report that names the machine and the + measurement is worth more than a patch that guesses. +- New identity resolvers for the sampler, especially for desktops that are not + this one. The resolver model is documented in the README. +- Documentation corrections, including corrections to this file. + +## What does not get merged + +- Dependencies. The whole point is that this runs on a bare Python with nothing + installed. If a change needs a package, it needs a very good argument. +- Client code, customer data, credentials, hostnames, or anything taken from a + machine that is not yours. Scrub before you paste. +- Claims in the UI that the sampler cannot back with a number. +- Anything that requires root. + +## Reporting a problem + +Open an issue. Include the workload row or the verdict line you saw, and the +output of `python3 server.py --demo` if the problem is in the interface. + +For anything that looks like a security problem, mail csass@binaryranch.com +rather than opening a public issue. + +## Authorship + +Contributors are credited in `AUTHORS.md`. Add yourself when your first change +lands. diff --git a/tools/check-dco.sh b/tools/check-dco.sh new file mode 100755 index 0000000..be3a095 --- /dev/null +++ b/tools/check-dco.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +# DCO check: every commit in the range must carry a Signed-off-by trailer that +# matches the commit author. Run locally as: ./tools/check-dco.sh origin/main..HEAD +set -euo pipefail + +range="${1:-origin/main..HEAD}" +fail=0 + +while IFS= read -r sha; do + [ -z "$sha" ] && continue + author_email="$(git log -1 --format='%ae' "$sha")" + body="$(git log -1 --format='%B' "$sha")" + + if ! printf '%s' "$body" | grep -qiE '^Signed-off-by: .+ <.+@.+>'; then + echo "MISSING sign-off: $sha $(git log -1 --format='%s' "$sha")" + fail=1 + continue + fi + + if ! printf '%s' "$body" | grep -qiE "^Signed-off-by: .+ <${author_email}>"; then + echo "MISMATCHED sign-off: $sha expected <$author_email>" + fail=1 + fi +done < <(git rev-list "$range") + +if [ "$fail" -ne 0 ]; then + echo + echo "Fix with: git commit -s --amend (or git rebase --signoff $range)" + exit 1 +fi +echo "DCO: all commits signed off"