From 46ed8c3bf61d1bc61804c3027de7e33892b9bc2e Mon Sep 17 00:00:00 2001 From: EllAchE <26192612+EllAchE@users.noreply.github.com> Date: Sun, 26 Jul 2026 00:43:34 -0400 Subject: [PATCH] Add org-wide community health defaults MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An outside contributor had no stated way to contribute and no private channel to report a vulnerability, so the rational move was a public issue. Org-wide search found zero CONTRIBUTING/CODE_OF_CONDUCT files and only one SECURITY.md. Files here are inherited by every org repo lacking its own, so this covers all five public repos at once — and any future ones. Security routes to the support@usestring.ai address already used by string-ai-mcp rather than a new one that would bounce; contribution conventions come from powhttp-mcp's documented squash + Conventional Commits release flow. LICENSE is deliberately absent: GitHub cannot default it. Co-Authored-By: Claude Opus 5 --- .github/ISSUE_TEMPLATE/bug_report.yml | 59 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 20 ++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 53 +++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 34 +++++++++++++ CODE_OF_CONDUCT.md | 51 +++++++++++++++++++ CONTRIBUTING.md | 52 +++++++++++++++++++ README.md | 28 ++++++++-- SECURITY.md | 43 ++++++++++++++++ SUPPORT.md | 39 ++++++++++++++ 9 files changed, 376 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..8246e64 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,59 @@ +name: Bug report +description: Something in this repository doesn't work the way it should +title: "[bug] " +body: + - type: markdown + attributes: + value: | + **If this is a security vulnerability, stop and email support@usestring.ai instead** — + see [SECURITY.md](https://github.com/usestring/.github/blob/main/SECURITY.md). + + **Never paste an API key, request log, or account detail into a public issue.** For anything + involving your account, quota, or a specific failing request against the hosted API, email + support@usestring.ai instead. + + - type: textarea + id: what-happened + attributes: + label: What happened + description: What you expected, and what you got instead. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction + description: > + The smallest thing that demonstrates the problem — commands, a code snippet, or a target URL. + Redact keys. + render: shell + validations: + required: true + + - type: input + id: version + attributes: + label: Version or commit + description: Release tag, npm version, or commit SHA. "main" is fine if you're on the tip. + validations: + required: true + + - type: input + id: environment + attributes: + label: Environment + description: OS and runtime version (Node, Bun, Go) where it matters. + placeholder: macOS 15.1, Node 22.9 + validations: + required: false + + - type: textarea + id: anything-else + attributes: + label: Anything else + description: > + Logs, stack traces, what you already tried and ruled out. If it's intermittent, say roughly + how often. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..aa1e215 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,20 @@ +# Keep blank issues available — not every report fits a form, and forcing one +# produces worse issues than allowing a free-form description. +blank_issues_enabled: true + +contact_links: + - name: Security vulnerability + url: https://github.com/usestring/.github/blob/main/SECURITY.md + about: Do not file publicly. Email support@usestring.ai — see the policy for what to include. + + - name: API, account, quota, or billing question + url: mailto:support@usestring.ai + about: Anything involving your API key or a specific failing request. Never paste a key into a public issue. + + - name: Documentation + url: https://portal.usestring.ai/docs + about: Web Access API reference and quickstart. + + - name: Web Access API benchmark + url: https://github.com/usestring/web-data-frontier-benchmark + about: Provider comparison results, methodology, and how to re-run the suite yourself. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..b93837d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,53 @@ +name: Feature request +description: Propose a change or addition before writing the code +title: "[feature] " +body: + - type: markdown + attributes: + value: | + For a **bug fix**, skip this and just send the PR — no issue needed. + + This form is for anything larger: a new feature, a new dependency, a refactor. Some of these + repos have constraints that aren't visible from outside (a provider's rate limits, a + fingerprint that breaks if header order changes), so it's worth a short conversation before + you spend a weekend on it. + + - type: textarea + id: problem + attributes: + label: The problem + description: > + What are you actually trying to do, and where does the current behaviour get in the way? + Describe the problem rather than the solution — it often changes what the right fix is. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: What you'd like to happen + description: Your proposed change. Rough is fine. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives you considered + description: > + Including workarounds you're using today. If you tried something and it didn't work, that's + useful — it saves us suggesting it back to you. + validations: + required: false + + - type: dropdown + id: willing-to-implement + attributes: + label: Would you want to implement this? + description: No wrong answer — it just tells us whether to scope for a review or for our own queue. + options: + - "Yes, if the approach is agreed" + - "Maybe, with some guidance" + - "No, just proposing it" + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ac29e99 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,34 @@ + + +## Summary + + + +## Testing + + + +## Notes for the reviewer + + + +--- + +- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, + `fix:`, `chore:`, `docs:`) — it becomes the squash commit message, and drives the version + bump in repos with release automation +- [ ] Read [CONTRIBUTING.md](https://github.com/usestring/.github/blob/main/CONTRIBUTING.md) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..bcc50a9 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,51 @@ +# Code of Conduct + +## The short version + +Be decent to people. We're here to build useful tools, and that goes better when contributors aren't +managing someone's behaviour on the side. + +## What's expected + +- **Assume the other person is competent and acting in good faith.** Most disagreements in a code + review are two people holding different context, not one person being wrong. +- **Criticise the code, not the author.** "This breaks when the response is chunked" is useful. + "Did you even test this?" is not, and it's the same information with the useful part removed. +- **Accept that maintainers say no.** A rejected PR usually means it doesn't fit constraints you + can't see from outside. Ask why; that's a fair question. Relitigating it across three threads is + not. +- **Respect the time of people answering you.** A clear reproduction, the version you're on, and + what you already tried — that's the difference between a question someone can answer in a minute + and one that costs an hour. + +## What isn't acceptable + +Harassment, discriminatory or demeaning remarks about anyone — including on the basis of race, sex, +gender identity or expression, sexual orientation, disability, appearance, body size, age, national +origin, or religion. Sexualised language or imagery. Personal or political attacks. Publishing +someone's private information. Sustained disruption of discussions. Deliberately intimidating, +stalking, or following someone. + +This applies in issues, pull requests, commit messages, code comments, and any other space where +you're participating as a contributor to these projects. + +## Enforcement + +Report it to **[support@usestring.ai](mailto:support@usestring.ai)**. Reports go to the maintainers +and stay confidential — we won't disclose the reporter's identity to the person reported without +asking first. + +We'll look into it and respond. Depending on what we find, that ranges from a private word, to +editing or removing content, to blocking someone from the org's repositories. Maintainers who don't +follow this themselves face the same consequences, and more of them — the standard exists to protect +contributors from the people with commit access, not the other way round. + +We're a small team and this document is deliberately short. It isn't a contract or an exhaustive +list of prohibited behaviour, and we'll use judgement on anything it doesn't name. If you think we +got a call wrong, say so — to us, at the address above. + +--- + +*If you'd prefer to read a longer and more formal treatment of the same ground, the +[Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) is the +widely adopted standard and nothing here is intended to conflict with it.* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cd9b19d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing + +Thanks for considering it. This is the org-wide default — a repo with its own `CONTRIBUTING.md` +overrides this one, so check for a local copy first. + +## Before you write code + +**For a bug fix, just send the PR.** No issue needed. A failing test or a reproduction in the +description is worth more than a paragraph of explanation. + +**For anything larger — a new feature, a dependency, a refactor — open an issue first.** Not +bureaucracy: some of these repos have constraints that aren't visible from the outside (a provider's +rate limits, a fingerprint that breaks if a header order changes), and we'd rather tell you before +you spend a weekend on it. + +## Pull requests + +- **One concern per PR.** A drive-by reformat bundled with a behaviour change is hard to review and + harder to revert. +- **Explain the why, not just the what.** We can read the diff. What we can't reconstruct is the + problem you hit and the approaches you rejected. +- **PR titles follow [Conventional Commits](https://www.conventionalcommits.org/)** — `feat:`, + `fix:`, `chore:`, `docs:`. We squash-merge, so your PR title becomes the commit message, and in + repos with release automation (currently [`powhttp-mcp`](https://github.com/usestring/powhttp-mcp)) + the prefix decides the version bump. Getting it wrong there means a release doesn't happen. +- **Keep the branch mergeable by merging `main` in**, not by rebasing. Squash discards the branch's + internal history anyway, so a merge commit costs nothing and a force-push loses review comments. + +## Running things costs money + +Several of these repos make real, billable API calls — +[`web-data-frontier-benchmark`](https://github.com/usestring/web-data-frontier-benchmark) most +obviously, where a full run is thousands of requests across fifteen paid providers. Start with +`--attempts 1` and a small `--tests` subset. Don't run a full suite to check a typo fix. + +## Benchmark results specifically + +If you're changing how a provider is called, say so explicitly and loudly. A provider configured in +a weaker mode than its competitors makes the published numbers wrong, and the entire value of that +repo is that the numbers are defensible. We'd rather merge a PR that says "this changes scrapfly's +request shape and here's why it's still apples-to-apples" than discover it later. + +Adding a provider is welcome and is documented in that repo's README. + +## Reporting a vulnerability + +**Not through a public issue or PR.** See [SECURITY.md](SECURITY.md). + +## Questions + +[SUPPORT.md](SUPPORT.md) has the routing — roughly, product and API questions go to support, +repo-specific questions go in that repo's issues. diff --git a/README.md b/README.md index bdc4eb1..c187026 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,28 @@ GitHub reads the profile README only from a repo named exactly `.github`, at exa `profile/README.md` — this repo was previously named `.usestring`, which is the *user*-profile convention (repo name == username) and gets no special treatment on an org. -This is also where org-wide community health defaults belong (`CONTRIBUTING.md`, `SECURITY.md`, -`ISSUE_TEMPLATE/`, `PULL_REQUEST_TEMPLATE.md`): any repo in the org that lacks its own copy -inherits the one here. None are defined yet. +## Org-wide community health defaults + +Every repo in the org that does **not** have its own copy of one of these files inherits the one +here. Adding a local file to a repo overrides the default for that repo only. + +| Path | Applies to | +| --- | --- | +| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute: when to open an issue first, PR expectations, Conventional Commit titles. | +| [`SECURITY.md`](SECURITY.md) | Vulnerability reporting via `support@usestring.ai`, and scope across repos + hosted services. | +| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Expected conduct and the enforcement contact. | +| [`SUPPORT.md`](SUPPORT.md) | Where a question goes: repo issue vs. private support vs. security. | +| [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) | Default PR body. | +| [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE) | Bug and feature forms, plus `config.yml` contact links. | + +Two rules worth knowing before editing these: + +- **`ISSUE_TEMPLATE/` is all-or-nothing.** If a repo has *anything* in its own + `.github/ISSUE_TEMPLATE/`, GitHub ignores this entire directory for that repo rather than merging + the two. Every other file overrides individually. +- **A `LICENSE` cannot be defaulted.** GitHub deliberately excludes it, because the license has to + travel with the code when a repo is cloned or packaged. Licenses stay per-repo. + +Lookup order within a repo is its own `.github/` folder, then its root, then `docs/`, and only then +this repo. Note that this only works while `.github` is **public** — a private default-files repo is +not supported. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..fdf59a3 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,43 @@ +# Security Policy + +## Reporting a vulnerability + +**Please do not report security vulnerabilities in a public GitHub issue, pull request, or +discussion.** A public report tells everyone else about the problem before there's a fix. + +Email **[support@usestring.ai](mailto:support@usestring.ai)** with: + +- the repository and version, commit, or endpoint affected +- a clear reproduction — the smallest one that demonstrates it +- what an attacker gets out of it, if that isn't obvious + +We'll acknowledge the report, work the fix privately, and tell you when it ships. If you'd like +credit in the release notes, say so and we'll include it; if you'd rather stay anonymous, that's +fine too. + +## Scope + +This is the org-wide default and covers the repositories under +[@usestring](https://github.com/usestring), plus our hosted services — the Web Access API +(`request.usestring.ai`), the hosted MCP endpoint (`mcp.usestring.ai`), and the portal +(`portal.usestring.ai`). + +A repository with its own `SECURITY.md` overrides this file for that repository. + +## Testing against our own API + +Our product fetches arbitrary URLs on your behalf, so the line between "using the API" and +"attacking it" can be genuinely unclear. Two asks: + +- **Test against your own infrastructure, or ours.** Don't use a String API key to attack a third + party and call it research. +- **Rate-limit yourself.** If you're probing for a denial-of-service condition, tell us first rather + than demonstrating it against production. + +If you're unsure whether something is in scope, email and ask — we'd much rather have that +conversation up front. + +## What we ask in return + +Give us a reasonable window to ship a fix before publishing. We don't currently run a paid bug +bounty; we do respond, we do fix things, and we do give credit. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..18f0437 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,39 @@ +# Support + +Where to go depends on what kind of problem you have. + +## Something's wrong with an open-source repo here + +**Open an issue in that repository.** Bugs, unexpected behaviour, a provider that stopped working, a +missing feature — that's the right place, and it's public so the next person with the same problem +finds it. + +Please include the version or commit, what you expected, what happened, and a reproduction. Issue +forms in these repos ask for exactly that. + +## Something's wrong with the API, your account, or billing + +**Email [support@usestring.ai](mailto:support@usestring.ai).** Anything involving your API key, a +specific failing request, quota, or an invoice needs to be private — don't paste a key or a request +log into a public issue. If you already did, rotate the key in the +[portal](https://portal.usestring.ai) first, then email us. + +Docs: **[portal.usestring.ai/docs](https://portal.usestring.ai/docs)** + +## You found a security vulnerability + +**Don't open an issue.** [SECURITY.md](SECURITY.md) has the process. + +## You want to contribute + +[CONTRIBUTING.md](CONTRIBUTING.md). + +## You want to talk to a human about using String for something bigger + +[Book a demo](https://www.usestring.ai) — managed pipelines and bespoke datasets aren't self-serve, +so a conversation is genuinely faster than a support thread. + +--- + +Response times are best-effort. We're a small team in New York; issues in these repos are not +covered by a commercial SLA unless you have one in your contract.