From bde8f406041ae724f13aeafef0d8f88e5b4a28e5 Mon Sep 17 00:00:00 2001 From: Bruno Perez Date: Sat, 23 May 2026 05:33:52 -0700 Subject: [PATCH] feat: guide contributions with issue forms and PR labels Add typed issue forms (add a model, add a provider, fix parameters, report incorrect data) with a chooser config, one low-friction PR template, and path-based auto-labeling. A label-sync workflow seeds the label set via the gh CLI so the forms have labels to apply. Also fix the CI badge, which still pointed at the old repo path. --- .github/ISSUE_TEMPLATE/add-model.yml | 83 ++++++++++++++++++++ .github/ISSUE_TEMPLATE/add-provider.yml | 62 +++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 12 +++ .github/ISSUE_TEMPLATE/incorrect-data.yml | 52 ++++++++++++ .github/ISSUE_TEMPLATE/parameter-request.yml | 45 ++++------- .github/PULL_REQUEST_TEMPLATE.md | 28 +++++++ .github/labeler.yml | 27 +++++++ .github/workflows/label-sync.yml | 37 +++++++++ .github/workflows/labeler.yml | 23 ++++++ CONTRIBUTING.md | 16 +++- README.md | 4 +- 11 files changed, 358 insertions(+), 31 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/add-model.yml create mode 100644 .github/ISSUE_TEMPLATE/add-provider.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/incorrect-data.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/labeler.yml create mode 100644 .github/workflows/label-sync.yml create mode 100644 .github/workflows/labeler.yml diff --git a/.github/ISSUE_TEMPLATE/add-model.yml b/.github/ISSUE_TEMPLATE/add-model.yml new file mode 100644 index 0000000..12a6ed8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/add-model.yml @@ -0,0 +1,83 @@ +# When a provider is added, add its slug to the Provider dropdown below. +name: Add a model +description: A provider we already track is missing one of its models. +title: "Add model: /" +labels: ["model"] +body: + - type: markdown + attributes: + value: | + Use this when the provider is already in the catalog but a model is missing. + If the provider itself isn't listed yet, use "Add a provider" instead. + + Please check [modelparams.dev](https://modelparams.dev) first so we don't track the same model twice. + + - type: dropdown + id: provider + attributes: + label: Provider + options: + - anthropic + - deepseek + - google + - mistral + - openai + validations: + required: true + + - type: input + id: model + attributes: + label: Model id + description: The provider-native id, spelled exactly as the API spells it. + placeholder: claude-opus-4-7, gpt-5.2, gemini-2.5-pro + validations: + required: true + + - type: dropdown + id: auth-type + attributes: + label: Auth type + description: "API key is the developer API. Subscription is the consumer app, like ChatGPT or Claude.ai." + options: + - API key + - Subscription + - Both + validations: + required: true + + - type: textarea + id: docs + attributes: + label: Official documentation + description: Link to the provider docs that list this model's parameters. Official references beat blog posts and screenshots. + placeholder: https://docs.anthropic.com/en/api/messages + validations: + required: true + + - type: textarea + id: params + attributes: + label: Known parameters + description: Optional. List any parameters you already know, with default, range, or allowed values if you have them. + placeholder: | + - temperature: number, default 1, range 0-1, sampling + - max_tokens: integer, range min 1, generation_length + validations: + required: false + + - type: textarea + id: notes + attributes: + label: Anything else + description: Optional. Restrictions, or parameters that differ between the API-key and subscription routes. + validations: + required: false + + - type: checkboxes + id: checks + attributes: + label: Quick check + options: + - label: This model isn't already listed on modelparams.dev. + required: true diff --git a/.github/ISSUE_TEMPLATE/add-provider.yml b/.github/ISSUE_TEMPLATE/add-provider.yml new file mode 100644 index 0000000..46a318a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/add-provider.yml @@ -0,0 +1,62 @@ +name: Add a provider +description: A model maker that isn't in the catalog yet (a new company or API). +title: "Add provider: " +labels: ["provider"] +body: + - type: markdown + attributes: + value: | + Use this for a provider we don't track at all. A new provider means a new folder under `models/`, and ideally a logo so it doesn't fall back to the generic mark. + + - type: input + id: name + attributes: + label: Provider name + placeholder: xAI, Cohere, Perplexity + validations: + required: true + + - type: input + id: slug + attributes: + label: Provider slug + description: Lowercase and kebab-case. This becomes the folder name under models/ and the provider field in each file. + placeholder: xai, cohere, perplexity + validations: + required: true + + - type: textarea + id: models + attributes: + label: First models to add + description: Which models should we start with, and is each one API key, subscription, or both? + placeholder: | + grok-4 (API key) + grok-4-heavy (API key) + validations: + required: true + + - type: textarea + id: docs + attributes: + label: API documentation + description: Link to the official parameter reference. + placeholder: https://docs.x.ai/api + validations: + required: true + + - type: textarea + id: logo + attributes: + label: Logo + description: Optional. Link to an official SVG logo, or say if you'll add one in your PR. Without a logo the site uses a generic placeholder. + validations: + required: false + + - type: checkboxes + id: checks + attributes: + label: Quick check + options: + - label: This provider isn't already listed on modelparams.dev. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..e31a366 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,12 @@ +# Blank issues stay enabled on purpose: the forms are here to guide, not to block. +blank_issues_enabled: true +contact_links: + - name: How to contribute + url: https://github.com/mnfst/modelparams.dev/blob/main/CONTRIBUTING.md + about: Read this before adding or editing model data. + - name: Model Parameters convention + url: https://github.com/mnfst/modelparams.dev/blob/main/docs/model-parameters-schema.md + about: The schema every model file follows. + - name: Browse the catalog + url: https://modelparams.dev + about: Check whether the model or parameter is already listed. diff --git a/.github/ISSUE_TEMPLATE/incorrect-data.yml b/.github/ISSUE_TEMPLATE/incorrect-data.yml new file mode 100644 index 0000000..84ad98b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/incorrect-data.yml @@ -0,0 +1,52 @@ +name: Report incorrect data +description: Something in the catalog is wrong (bad default, wrong range, a parameter the API doesn't accept). +title: "Incorrect data: " +labels: ["incorrect-data"] +body: + - type: markdown + attributes: + value: | + Use this when a value in the catalog is wrong. For a model or provider that's missing entirely, use the other forms. + + - type: input + id: model + attributes: + label: Affected model + description: The id as shown on the site. + placeholder: anthropic/claude-opus-4-7, openai/gpt-5.2-subscription + validations: + required: true + + - type: dropdown + id: kind + attributes: + label: What's wrong? + options: + - Wrong default + - Wrong range (min, max, or step) + - Wrong enum values + - Wrong applicability rule + - Parameter is listed but the API doesn't accept it + - Parameter is missing + - Wrong provider or model id + - Something else + validations: + required: true + + - type: textarea + id: detail + attributes: + label: What it says now, and what it should be + description: Be specific. Name the parameter path, the current value, and the correct one. + placeholder: | + temperature shows a range of 0-2, but the API rejects anything above 1. + validations: + required: true + + - type: textarea + id: source + attributes: + label: Official source + description: Link to the docs that back up the correction. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/parameter-request.yml b/.github/ISSUE_TEMPLATE/parameter-request.yml index bd53028..4e6b305 100644 --- a/.github/ISSUE_TEMPLATE/parameter-request.yml +++ b/.github/ISSUE_TEMPLATE/parameter-request.yml @@ -1,29 +1,21 @@ -name: Request model parameters -description: Request a new or updated provider/model parameter entry. +name: Add or fix parameters on a model +description: A model is already listed, but its parameter list is incomplete or out of date. +title: "Parameters: /" +labels: ["parameters"] body: - type: markdown attributes: value: | - Use this form to request parameter coverage for a model in modelparameters.dev. - Suggested issue title: `/: parameter coverage`. + Use this when the model is already on the site but its parameters are missing or stale. If a value on an existing parameter is simply wrong, "Report incorrect data" is the better fit. - This catalog covers configurable request parameters such as `temperature`, `top_p`, `max_tokens`, `reasoning_effort`, and `thinking.type`. It does not track pricing, streaming support, auth setup, endpoints, fallback behavior, or proxy behavior. - - - type: input - id: provider - attributes: - label: Provider - description: Use the provider slug when you know it. - placeholder: openai, anthropic, google, mistral - validations: - required: true + This catalog covers configurable request parameters such as `temperature`, `top_p`, `max_tokens`, `reasoning_effort`, and `thinking.type`. It does not track pricing, rate limits, endpoints, auth setup, streaming, or proxy behavior. - type: input id: model attributes: label: Model - description: Use the provider-native model id. - placeholder: gpt-5, claude-sonnet-4-5, gemini-2.5-pro + description: The id as shown on the site. + placeholder: anthropic/claude-opus-4-7 validations: required: true @@ -31,12 +23,11 @@ body: id: auth-type attributes: label: Auth type - description: Pick the route this request applies to. + description: Pick the route this applies to. options: - API key - Subscription - Both - - Not sure validations: required: true @@ -44,7 +35,7 @@ body: id: docs attributes: label: Official documentation - description: Link to the provider docs that define these parameters. Official references are preferred over blog posts or screenshots. + description: Link to the provider docs that define these parameters. placeholder: | https://docs.example.com/api-reference/chat/create validations: @@ -54,11 +45,10 @@ body: id: parameters attributes: label: Parameters to add or update - description: List the parameters you want added. Include path, type, default, allowed values, numeric range, and applicability rules if you know them. + description: List each one. Include path, type, default, allowed values, range, and any applicability rule you know. placeholder: | - - `temperature`: number, default 1, range 0-2, sampling - - `max_tokens`: integer, range min 1, generation_length - - `reasoning_effort`: enum, values `low`, `medium`, `high`, reasoning + - reasoning_effort: enum, values low/medium/high, reasoning + - top_p: number, default 1, range 0-1, sampling validations: required: true @@ -66,8 +56,8 @@ body: id: notes attributes: label: Notes - description: Add anything maintainers should know, such as model-specific restrictions or parameters that are accepted by one auth type but not the other. - placeholder: This parameter is only available when extended thinking is disabled. + description: Optional. Model-specific restrictions, or a parameter that one auth type accepts and the other doesn't. + placeholder: This parameter only applies when extended thinking is off. validations: required: false @@ -75,9 +65,6 @@ body: id: scope attributes: label: Scope check - description: Please confirm this request fits the MPS catalog scope. options: - - label: This request is about configurable model request parameters, not pricing, rate limits, endpoints, auth setup, streaming support, or proxy behavior. - required: true - - label: I linked the closest official provider documentation I could find. + - label: This is about configurable request parameters, not pricing, rate limits, endpoints, auth setup, or streaming. required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..6f28516 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,28 @@ + + +## What this changes + + + +## Type of change + +Tick whatever fits. This just helps reviewers triage; nothing is enforced. + +- [ ] Add a model (new YAML file under `models/`) +- [ ] Add a provider (new folder under `models/`, plus a logo) +- [ ] Add or update parameters on an existing model +- [ ] Fix incorrect data (default, range, values, applicability) +- [ ] Site or tooling (code under `src/`, docs, CI) + +## Source + + + +## Before opening + +- [ ] `npm run validate` and `npm test` pass locally +- [ ] Filenames follow the convention: `models//.yaml`, or `-subscription.yaml` for the subscription route +- [ ] No existing parameter was removed (removals are blocked, see CONTRIBUTING) diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 0000000..7524788 --- /dev/null +++ b/.github/labeler.yml @@ -0,0 +1,27 @@ +# Auto-labels PRs by the files they touch. Read by .github/workflows/labeler.yml. +# A provider PR usually touches both models/ and a logo, so it lands two labels. +model: + - changed-files: + - any-glob-to-any-file: + - "models/**" + +provider: + - changed-files: + - any-glob-to-any-file: + - "src/client/logos/**" + +site: + - changed-files: + - any-glob-to-any-file: + - "src/**" + - "tests/**" + - "tailwind.config.ts" + - "postcss.config.cjs" + - "vitest.config.ts" + +meta: + - changed-files: + - any-glob-to-any-file: + - ".github/**" + - "docs/**" + - "*.md" diff --git a/.github/workflows/label-sync.yml b/.github/workflows/label-sync.yml new file mode 100644 index 0000000..5ca1d4d --- /dev/null +++ b/.github/workflows/label-sync.yml @@ -0,0 +1,37 @@ +name: Sync labels + +# Creates (or updates) the label set the issue forms and the labeler rely on. +# Runs on merge to main whenever this file changes, and on demand. Edit a label +# here and the next run brings the repo in line. Uses the built-in gh CLI, so +# there's no third-party action to trust. + +on: + workflow_dispatch: + push: + branches: [main] + paths: + - ".github/workflows/label-sync.yml" + +permissions: + issues: write + +jobs: + sync: + name: Create or update labels + runs-on: ubuntu-latest + env: + GH_TOKEN: ${{ github.token }} + steps: + - name: Sync + run: | + set -euo pipefail + sync() { + gh label create "$1" --color "$2" --description "$3" --force --repo "$GITHUB_REPOSITORY" + } + sync "model" "1d76db" "Add a model that's missing" + sync "provider" "5319e7" "Add a provider that's missing" + sync "parameters" "0e8a16" "Add or update parameters on a model" + sync "incorrect-data" "d93f0b" "A value in the catalog is wrong" + sync "site" "c5def5" "Website code or tooling" + sync "meta" "ededed" "Repo docs, CI, and config" + sync "allow-param-removal" "fbca04" "Maintainer override: allow a parameter removal" diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 0000000..fd64c97 --- /dev/null +++ b/.github/workflows/labeler.yml @@ -0,0 +1,23 @@ +name: Labeler + +# Labels PRs by the paths they touch, using .github/labeler.yml. +# Runs as pull_request_target so it works on fork PRs too. It only reads the +# list of changed files and applies labels; it never checks out or runs the +# PR's code, so the elevated token stays safe. + +on: + pull_request_target: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + label: + name: Apply path labels + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@v5 + with: + sync-labels: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ce0dc18..cd8c4c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,17 @@ Thanks for helping build the catalog. There are two main ways to contribute: **a The formal catalog convention is the [Model Parameters convention](docs/model-parameters-schema.md). +## Found a problem, or want something added? + +Open an issue. The [issue forms](https://github.com/mnfst/modelparams.dev/issues/new/choose) cover the usual cases: + +- Add a model, when a provider we already track is missing one of its models. +- Add a provider, for a maker that isn't in the catalog yet. +- Add or fix parameters, when a model is listed but its parameters are incomplete or stale. +- Report incorrect data, when a default, range, value, or rule is wrong. + +You don't need to know the schema to file one. A link to the official docs is the most useful thing you can include. + ## Adding or updating a model 1. **Pick the filename.** API-key models are bare; subscription models get a `-subscription` suffix. @@ -149,6 +160,9 @@ Conventions: ## Pull requests +The PR description starts from a template with a short "type of change" checklist. Tick what fits so a reviewer can see at a glance what the PR does. It's a hint, not a gate. + - One change per PR, small and focused. - Make sure CI is green before requesting review. -- For new providers, link to the official docs URL in the PR description. +- A bot labels your PR by the files it touches (`model`, `provider`, `site`, `meta`). Nothing for you to do. +- For a new provider, link the official docs and add a logo at `src/client/logos/.svg`. Without one, the site shows a generic mark. diff --git a/README.md b/README.md index 5ea3c09..e36c103 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > An open, community-maintained catalog of LLM model parameters. -[![CI](https://github.com/mnfst/modelparameters.dev/actions/workflows/ci.yml/badge.svg)](https://github.com/mnfst/modelparameters.dev/actions/workflows/ci.yml) +[![CI](https://github.com/mnfst/modelparams.dev/actions/workflows/ci.yml/badge.svg)](https://github.com/mnfst/modelparams.dev/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [modelparams.dev](https://modelparams.dev) is an open-source database that lists the parameters available for popular AI models. It is heavily inspired on [models.dev](https://github.com/anomalyco/models.dev) and we use it at [Manifest](https://manifest.build/). @@ -27,6 +27,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: 2. Add a YAML file at `models//.yaml` (or `models//-subscription.yaml`). 3. Open a PR. CI validates against the schema and rebuilds. +Don't want to open a PR? [File an issue](https://github.com/mnfst/modelparams.dev/issues/new/choose) with the model and a link to the official docs, and someone will pick it up. + ## Local development ```bash