https://github.com/hyperspy/hyperspy-proposals
Central hub for HyperSpy ecosystem architecture proposals
https://github.com/hyperspy/hyperspy-proposals
Last synced: 5 days ago
JSON representation
Central hub for HyperSpy ecosystem architecture proposals
- Host: GitHub
- URL: https://github.com/hyperspy/hyperspy-proposals
- Owner: hyperspy
- License: cc-by-sa-4.0
- Created: 2026-07-01T10:04:44.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-07-16T10:25:37.000Z (16 days ago)
- Last Synced: 2026-07-16T12:15:02.555Z (16 days ago)
- Language: Python
- Size: 51.8 KB
- Stars: 0
- Watchers: 0
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# HyperSpy Proposals
This 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`.
## When is a proposal required?
| Contribution type | Proposal required? |
|---|---|
| **AI-assisted, non-trivial** | **Yes** — implementation PRs will not be reviewed without an accepted proposal |
| **AI-assisted, trivial** | No — the PR review is sufficient |
| **Human-only, non-trivial** | **Recommended** — not mandatory, but strongly encouraged for large changes |
| **Human-only, trivial** | No — the PR review is sufficient |
### Why require proposals for AI-assisted contributions?
AI 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."
## How to submit a proposal
1. **Create a markdown file** named `-.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.
2. **Start the file with a YAML metadata block:**
```yaml
---
proposal: 0001
title: "hspy-spec — a metadata specification system for HyperSpy 3.0"
type: Architecture # Architecture | Feature | Bugfix | Process
target_branch: hyperspy/hyperspy:RELEASE_next_major
target_repos: [hyperspy/hyperspy, hyperspy/rosettasciio, hyperspy/hspy-spec]
status: review # review | accepted | implemented | superseded
ai_assisted: true
created: 2026-06-30
---
```
3. **Write the proposal.** A proposal is a decision document, not a design document. Include these sections:
- **Summary** — 2-3 sentences: what, why, what decision is needed
- **Problem** — concrete, with examples
- **Proposed approach** — high-level, with an alternatives considered table
- **Impact** — what breaks, migration path, effort estimate
- **Scope** — what's in, what's explicitly NOT in
- **References** — links to discussions, issues, PRs
- **Technical design** — mandatory: tree diagrams, encoding tables, code samples, governance models
See [AGENTS.md](AGENTS.md) for detailed guidance on each section.
4. **Open a PR** to this repository with the markdown file.
5. **Tag relevant people** for review.** Cross-reference from related issues in the target repos.
6. **Iterate.** Address review comments by pushing commits to your PR branch. Reviewers can see the changes and resolve/unresolve comments.
## How review works
- **Inline comments**: Reviewers comment on specific lines/paragraphs (standard GitHub PR review)
- **Suggest changes**: Reviewers can propose edits directly
- **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.
- **CI checks**: Every PR runs rumdl, link-check, and frontmatter-validation
- **Consensus**: A proposal is accepted when maintainers of the affected repos approve. For cross-repo proposals, maintainers of ALL affected repos should approve.
- **Iterate**: Address review comments by pushing commits to your PR branch. Once consensus is reached, summarize feedback and revised decisions before merging.
## After acceptance
1. **Merge the proposal PR.** The proposal is now accepted and lives in this repo permanently.
2. **Start implementation.** Open implementation PRs in the target repos (e.g., `hyperspy/hyperspy`, `hyperspy/rosettasciio`).
3. **Reference the proposal.** In each implementation PR, include: "Implements [proposal 0001](https://github.com/hyperspy/hyperspy-proposals/pull/1)."
4. **Update proposal status.** After implementation is merged, update the proposal's metadata: `status: implemented`.
5. **Review the implementation.** The implementation PRs go through normal code review. Reviewers can check the implementation against the accepted proposal.
## Proposal types
| Type | Description | Example |
|------|-------------|---------|
| `Architecture` | System design, new packages, major restructuring | hspy-spec, SignalCollection API |
| `Feature` | New user-facing functionality | New signal type, new analysis method |
| `Bugfix` | Significant bug fix that changes behavior | Metadata migration overhaul |
| `Process` | Development process change | This proposals repo, CI changes |
## Target branches
Proposals specify which branch the implementation targets:
| Branch | When to use |
|--------|-------------|
| `RELEASE_next_patch` | Bug fixes, no new features |
| `RELEASE_next_minor` | New features, backward-compatible changes |
| `RELEASE_next_major` | Breaking API changes, major restructuring |
A proposal can target multiple branches if needed (e.g., deprecation in `RELEASE_next_minor`, removal in `RELEASE_next_major`).
## Running checks locally
Every PR runs the checks defined in `.github/workflows/ci.yml`.
You can run the same checks before pushing.
### Recommended: pixi
[pixi](https://pixi.sh/) is the fastest way to get a reproducible, project-local environment.
Install pixi, then run:
```bash
pixi install
pixi run check
```
`pixi install` creates the conda environment in `.pixi/`.
`pixi run check` runs frontmatter validation, rumdl, and link checks.
Available tasks:
| Task | What it runs |
|---|---|
| `pixi run check` | Runs frontmatter, rumdl, and link checks |
| `pixi run fix` | Runs `rumdl fmt` to auto-fix markdown issues |
| `pixi run lint` | Runs `rumdl check` only |
| `pixi run links` | Runs `lychee` link check only |
| `pixi run frontmatter` | Runs the proposal frontmatter validator only |
| `pixi run pre-commit` | Runs all pre-commit hooks on all files |
### Formatting conventions
The repository enforces [rumdl](https://github.com/rvben/rumdl)
rules defined in `.rumdl.toml`. Key conventions:
- **Ordered lists** use sequential numbering (1, 2, 3…).
- **Headings** use ATX style (`#`, `##`, `###`).
- **Links** must have descriptive text — no bare URLs.
- **Blank lines** must surround headings, lists, and fenced code blocks.
- **Fenced code blocks** must specify a language.
The full rule set is in `.rumdl.toml`. Run `pixi run fix` to auto-correct
most issues.
### Alternative: conda
If you use [conda](https://conda.io/) or [mamba](https://mamba.readthedocs.io/):
```bash
conda env create -f environment.yml
conda activate hyperspy-proposals
python .github/scripts/validate-frontmatter.py
rumdl check .
lychee --require-https .
```
### Not recommended: pip-only
A `requirements.txt` file is provided for pip users, but it does not install `lychee`.
You will have to install that separately. Use this only if you cannot use pixi or conda.
### Reproducing CI failures
If a CI run fails, you can reproduce the exact environment locally. Download the
`pixi.lock` artifact from the **Summary** tab of the GitHub Actions run, place it
in the repository root, and run:
```bash
pixi install
```
This will recreate the precise dependency versions used in CI.
### Pre-commit hook (optional but recommended)
[pre-commit](https://pre-commit.com/) runs the rumdl and frontmatter checks automatically when you commit, including auto-fixes for many markdown issues.
Install it once:
```bash
pre-commit install
```
Then `git commit` will run the hooks on staged files. To check all files manually:
```bash
pixi run pre-commit
```
## For AI agents
See [AGENTS.md](AGENTS.md).
## License
Proposals 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).