{"id":51907234,"url":"https://github.com/hyperspy/hyperspy-proposals","last_synced_at":"2026-07-27T00:30:41.103Z","repository":{"id":368650013,"uuid":"1285964446","full_name":"hyperspy/hyperspy-proposals","owner":"hyperspy","description":"Central hub for HyperSpy ecosystem architecture proposals","archived":false,"fork":false,"pushed_at":"2026-07-16T10:25:37.000Z","size":53,"stargazers_count":0,"open_issues_count":6,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-16T12:15:02.555Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-sa-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperspy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-01T10:04:44.000Z","updated_at":"2026-07-16T10:25:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyperspy/hyperspy-proposals","commit_stats":null,"previous_names":["hyperspy/hyperspy-proposals"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hyperspy/hyperspy-proposals","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperspy%2Fhyperspy-proposals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperspy%2Fhyperspy-proposals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperspy%2Fhyperspy-proposals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperspy%2Fhyperspy-proposals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperspy","download_url":"https://codeload.github.com/hyperspy/hyperspy-proposals/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperspy%2Fhyperspy-proposals/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35932861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-27T00:30:40.616Z","updated_at":"2026-07-27T00:30:41.088Z","avatar_url":"https://github.com/hyperspy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperSpy Proposals\n\nThis repository hosts proposals for changes to repositories in the [hyperspy](https://github.com/hyperspy) GitHub organization — including `hyperspy/hyperspy`, `hyperspy/rosettasciio`, `hyperspy/hspy-spec`, and `hyperspy/hyperspy-ml`.\n\n## When is a proposal required?\n\n| Contribution type | Proposal required? |\n|---|---|\n| **AI-assisted, non-trivial** | **Yes** — implementation PRs will not be reviewed without an accepted proposal |\n| **AI-assisted, trivial** | No — the PR review is sufficient |\n| **Human-only, non-trivial** | **Recommended** — not mandatory, but strongly encouraged for large changes |\n| **Human-only, trivial** | No — the PR review is sufficient |\n\n### Why require proposals for AI-assisted contributions?\n\nAI coding tools can generate large amounts of code quickly. A proposal gives the community a chance to review the **approach** before reviewing the **implementation** — much cheaper to fix a wrong approach in a markdown file than in hundreds of lines of code. It also creates an audit trail: \"this AI-generated change was reviewed and approved.\"\n\n## How to submit a proposal\n\n1. **Create a markdown file** named `\u003cPR_NUMBER\u003e-\u003cshort-slug\u003e.md` in the `proposals/` directory (e.g., `proposals/0001-hspy-spec.md`). Use the PR number you'll get when you open the PR — if unsure, use a placeholder and rename after.\n\n2. **Start the file with a YAML metadata block:**\n\n   ```yaml\n   ---\n   proposal: 0001\n   title: \"hspy-spec — a metadata specification system for HyperSpy 3.0\"\n   type: Architecture          # Architecture | Feature | Bugfix | Process\n   target_branch: hyperspy/hyperspy:RELEASE_next_major\n   target_repos: [hyperspy/hyperspy, hyperspy/rosettasciio, hyperspy/hspy-spec]\n   status: review              # review | accepted | implemented | superseded\n   ai_assisted: true\n   created: 2026-06-30\n   ---\n   ```\n\n3. **Write the proposal.** A proposal is a decision document, not a design document. Include these sections:\n\n   - **Summary** — 2-3 sentences: what, why, what decision is needed\n   - **Problem** — concrete, with examples\n   - **Proposed approach** — high-level, with an alternatives considered table\n   - **Impact** — what breaks, migration path, effort estimate\n   - **Scope** — what's in, what's explicitly NOT in\n   - **References** — links to discussions, issues, PRs\n   - **Technical design** — mandatory: tree diagrams, encoding tables, code samples, governance models\n\n   See [AGENTS.md](AGENTS.md) for detailed guidance on each section.\n\n4. **Open a PR** to this repository with the markdown file.\n\n5. **Tag relevant people** for review.** Cross-reference from related issues in the target repos.\n\n6. **Iterate.** Address review comments by pushing commits to your PR branch. Reviewers can see the changes and resolve/unresolve comments.\n\n## How review works\n\n- **Inline comments**: Reviewers comment on specific lines/paragraphs (standard GitHub PR review)\n- **Suggest changes**: Reviewers can propose edits directly\n- **Rendered view**: Click **Display the rich diff** in the **Files changed** tab to see proposals rendered as formatted markdown instead of raw source. Or use **View file** to open the full rendered document.\n- **CI checks**: Every PR runs rumdl, link-check, and frontmatter-validation\n- **Consensus**: A proposal is accepted when maintainers of the affected repos approve. For cross-repo proposals, maintainers of ALL affected repos should approve.\n- **Iterate**: Address review comments by pushing commits to your PR branch. Once consensus is reached, summarize feedback and revised decisions before merging.\n\n## After acceptance\n\n1. **Merge the proposal PR.** The proposal is now accepted and lives in this repo permanently.\n\n2. **Start implementation.** Open implementation PRs in the target repos (e.g., `hyperspy/hyperspy`, `hyperspy/rosettasciio`).\n\n3. **Reference the proposal.** In each implementation PR, include: \"Implements [proposal 0001](https://github.com/hyperspy/hyperspy-proposals/pull/1).\"\n\n4. **Update proposal status.** After implementation is merged, update the proposal's metadata: `status: implemented`.\n\n5. **Review the implementation.** The implementation PRs go through normal code review. Reviewers can check the implementation against the accepted proposal.\n\n## Proposal types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `Architecture` | System design, new packages, major restructuring | hspy-spec, SignalCollection API |\n| `Feature` | New user-facing functionality | New signal type, new analysis method |\n| `Bugfix` | Significant bug fix that changes behavior | Metadata migration overhaul |\n| `Process` | Development process change | This proposals repo, CI changes |\n\n## Target branches\n\nProposals specify which branch the implementation targets:\n\n| Branch | When to use |\n|--------|-------------|\n| `RELEASE_next_patch` | Bug fixes, no new features |\n| `RELEASE_next_minor` | New features, backward-compatible changes |\n| `RELEASE_next_major` | Breaking API changes, major restructuring |\n\nA proposal can target multiple branches if needed (e.g., deprecation in `RELEASE_next_minor`, removal in `RELEASE_next_major`).\n\n## Running checks locally\n\nEvery PR runs the checks defined in `.github/workflows/ci.yml`.\nYou can run the same checks before pushing.\n\n### Recommended: pixi\n\n[pixi](https://pixi.sh/) is the fastest way to get a reproducible, project-local environment.\nInstall pixi, then run:\n\n```bash\npixi install\npixi run check\n```\n\n`pixi install` creates the conda environment in `.pixi/`.\n`pixi run check` runs frontmatter validation, rumdl, and link checks.\n\nAvailable tasks:\n\n| Task | What it runs |\n|---|---|\n| `pixi run check` | Runs frontmatter, rumdl, and link checks |\n| `pixi run fix` | Runs `rumdl fmt` to auto-fix markdown issues |\n| `pixi run lint` | Runs `rumdl check` only |\n| `pixi run links` | Runs `lychee` link check only |\n| `pixi run frontmatter` | Runs the proposal frontmatter validator only |\n| `pixi run pre-commit` | Runs all pre-commit hooks on all files |\n\n### Formatting conventions\n\nThe repository enforces [rumdl](https://github.com/rvben/rumdl)\nrules defined in `.rumdl.toml`. Key conventions:\n\n- **Ordered lists** use sequential numbering (1, 2, 3…).\n- **Headings** use ATX style (`#`, `##`, `###`).\n- **Links** must have descriptive text — no bare URLs.\n- **Blank lines** must surround headings, lists, and fenced code blocks.\n- **Fenced code blocks** must specify a language.\n\nThe full rule set is in `.rumdl.toml`. Run `pixi run fix` to auto-correct\nmost issues.\n\n### Alternative: conda\n\nIf you use [conda](https://conda.io/) or [mamba](https://mamba.readthedocs.io/):\n\n```bash\nconda env create -f environment.yml\nconda activate hyperspy-proposals\npython .github/scripts/validate-frontmatter.py\nrumdl check .\nlychee --require-https .\n```\n\n### Not recommended: pip-only\n\nA `requirements.txt` file is provided for pip users, but it does not install `lychee`.\nYou will have to install that separately. Use this only if you cannot use pixi or conda.\n\n### Reproducing CI failures\n\nIf a CI run fails, you can reproduce the exact environment locally. Download the\n`pixi.lock` artifact from the **Summary** tab of the GitHub Actions run, place it\nin the repository root, and run:\n\n```bash\npixi install\n```\n\nThis will recreate the precise dependency versions used in CI.\n\n### Pre-commit hook (optional but recommended)\n\n[pre-commit](https://pre-commit.com/) runs the rumdl and frontmatter checks automatically when you commit, including auto-fixes for many markdown issues.\n\nInstall it once:\n\n```bash\npre-commit install\n```\n\nThen `git commit` will run the hooks on staged files. To check all files manually:\n\n```bash\npixi run pre-commit\n```\n\n## For AI agents\n\nSee [AGENTS.md](AGENTS.md).\n\n## License\n\nProposals in this repository are licensed under [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/) (Creative Commons Attribution-ShareAlike 4.0 International).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperspy%2Fhyperspy-proposals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperspy%2Fhyperspy-proposals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperspy%2Fhyperspy-proposals/lists"}