Add community files (citation, contributing, security, templates); refresh .spi.yml

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,47 @@
+name: Bug report
+description: A file reads wrongly, fails to read, or crashes
+labels: ["bug"]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: FormatoKit version
+      description: A release tag or a commit.
+    validations:
+      required: true
+  - type: dropdown
+    id: format
+    attributes:
+      label: Format
+      options:
+        - DigitalMicrograph (dm3, dm4)
+        - Velox EMD
+        - TIFF
+        - MRC
+        - EMPAD
+        - Merlin MIB
+        - HDF5 / py4DSTEM
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did, what you expected and what you got. Include the full error message.
+    validations:
+      required: true
+  - type: textarea
+    id: comparison
+    attributes:
+      label: RosettaSciIO result
+      description: If you can, what RosettaSciIO returns for the same file (shape, axes, a few values).
+  - type: input
+    id: system
+    attributes:
+      label: macOS and Xcode versions
+  - type: textarea
+    id: file
+    attributes:
+      label: Example file
+      description: A link to the file or a trimmed copy, if you may share it.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature request
+description: Ask for a file format or an option
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What would you like FormatoKit to do
+      description: For a new format, name it, the file extensions and the instrument or software that writes it.
+    validations:
+      required: true
+  - type: textarea
+    id: reference
+    attributes:
+      label: Reference
+      description: Does RosettaSciIO read this? Link its documentation or a public sample file if you know one.
+  - type: textarea
+    id: use
+    attributes:
+      label: What you need it for

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## What this changes
+
+## Why
+
+## Checks
+
+- [ ] `swift test` passes
+- [ ] New or changed behaviour has a test that fails without the change
+- [ ] Numbers a reader returns are compared with RosettaSciIO (no loosened tolerance)
+- [ ] Documentation updated (DocC pages, `docs/parity.md`) where the change touches it

.spi.yml

@@ -1,9 +1,8 @@
-# Swift Package Index: which modules get hosted DocC documentation. Written 2026-10-15 (0.0.3); listing on the Index is the
-# owner's, once the repository is public. The package declares macOS 15 / iOS 18 (0.2.1; the shipped libhdf5 is
-# arm64 macOS), so the docs build on the Index's macOS SwiftPM builder. The empty format modules (FormatoMRC, FormatoEMPAD, FormatoMSA) are
-# left out until they hold API.
+# Swift Package Index: which modules get hosted DocC documentation. The package declares macOS 15 / iOS 18 (the shipped
+# libhdf5 is arm64 macOS), so the docs build on the Index's macOS SwiftPM builder. FormatoMSA is left out until it holds API
+# (it is an empty placeholder today).
 version: 1
 builder:
   configs:
     - platform: macos-spm
-      documentation_targets: [FormatoCore, FormatoDM, FormatoEMD, FormatoHDF5, FormatoTIFF]
+      documentation_targets: [FormatoCore, FormatoDM, FormatoEMD, FormatoHDF5, FormatoTIFF, FormatoMRC, FormatoEMPAD, FormatoMIB]

CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use FormatoKit in your work, please cite it using the metadata below."
+title: "FormatoKit"
+type: software
+abstract: >-
+  FormatoKit is a Swift library for reading electron microscopy file formats (Gatan DigitalMicrograph,
+  Velox EMD, TIFF, MRC, EMPAD, Merlin MIB and py4DSTEM-style HDF5) on macOS and iOS. It follows
+  RosettaSciIO and is checked against it.
+authors:
+  - name: "mac4DSTEM contributors"
+license: GPL-3.0
+repository-code: "https://github.com/mac4DSTEM/FormatoKit"
+keywords:
+  - electron microscopy
+  - file formats
+  - Swift
+  - RosettaSciIO
+references:
+  - type: software
+    title: "RosettaSciIO"
+    authors:
+      - name: "The HyperSpy developers"
+    repository-code: "https://github.com/hyperspy/rosettasciio"
+    license: GPL-3.0-or-later
+    notes: "The reference implementation FormatoKit follows and is checked against."

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to FormatoKit
+
+Thank you for your interest. FormatoKit reads electron microscopy file formats in Swift and is checked against
+[RosettaSciIO](https://github.com/hyperspy/rosettasciio). Bug reports, new test files and pull requests are welcome.
+
+## Building and testing
+
+You need macOS 15 or later on Apple silicon and Xcode 26 or later (Swift 6.2).
+
+```sh
+swift build
+swift test
+```
+
+The libhdf5 libraries the HDF5 and EMD readers need are binary targets of the package. If the release they are
+downloaded from is not available to you, build them locally and point the package at them:
+
+```sh
+tools/xcframework/build.sh --local
+FORMATO_LOCAL_XCFRAMEWORKS=1 swift test -c release
+```
+
+`tools/test.sh` does both steps for you and also checks the build for warnings.
+
+## How the tests work
+
+- Tests use [Swift Testing](https://developer.apple.com/documentation/testing) (`import Testing`, `@Test`, `#expect`),
+  not XCTest.
+- What a reader returns (shapes, values, axes, units, metadata) is compared bit for bit with what RosettaSciIO returns
+  for the same file. The expected values are committed as fixtures next to the tests, so you can run them without
+  installing Python.
+- If a test disagrees with RosettaSciIO, treat it as a bug in the reader. Please do not loosen a tolerance to make it
+  pass. If you believe RosettaSciIO is wrong, say so in the pull request and show why.
+- New behaviour needs a test that fails without your change and passes with it. A small file that shows the case is
+  the best test data; please check you may share it.
+
+## Pull requests
+
+1. Open an issue first for anything larger than a fix, so we can agree on the approach.
+2. Keep each pull request focused on one change.
+3. Update the documentation that your change touches (the DocC pages in `Sources/<Module>/<Module>.docc` and
+   `docs/parity.md` for format support).
+4. Make sure `swift test` passes.
+
+By contributing you agree that your work is licensed under GPL-3.0, like the rest of the package.
+
+## Reporting issues
+
+Use the issue templates. For a file that will not read, the most useful report is the format, the error message,
+the version of FormatoKit, and (if you can share it) the file or a trimmed copy.

SECURITY.md

@@ -0,0 +1,16 @@
+# Security policy
+
+FormatoKit parses files from instruments and from other people, so a crafted file that crashes a reader, reads past
+the end of a buffer or uses unbounded memory is a security issue.
+
+## Reporting a vulnerability
+
+Please report it privately with GitHub's private vulnerability reporting: open the repository's **Security** tab and
+choose **Report a vulnerability**. Please do not open a public issue for it. Include the FormatoKit version, the
+format and, if you can, a file that reproduces the problem.
+
+Fixes are made on a best-effort basis and released in the next version.
+
+## Supported versions
+
+Only the latest release receives fixes.