Community¶

ASTRA is an open project, intentionally early. The schema, tooling, and documentation are all developed in the open on GitHub, and the most valuable thing the project can have right now — while it is still in alpha — is contact with people who are actually trying to use it.

If you find ASTRA useful, awkward, surprising, missing something, or just adjacent to a problem you care about, the project wants to hear from you.

Where to find us¶

When in doubt about which repo to file an issue in: schema or specification questions go to astra-spec; CLI / validator / paper-tool questions go to ASTRA.

What's most useful right now¶

In alpha, three kinds of contribution are worth more than they will be later:

• Real-analysis attempts. Take an analysis you actually ran and try to express it in ASTRA. Report what fits, what doesn't, and where the spec forced you to invent a workaround. These reports are the single best signal for what to fix at the schema level.
• Schema review. Read the specification and the schema reference with an adversarial eye. Ambiguity, missing constraints, and reserved-name collisions are easier to fix now than after the format has consumers.
• Downstream tooling experiments. Build something that consumes an ASTRA spec — a runner, a renderer, a retrieval index, a JSON-Schema-driven editor. Even a prototype tells the project what is awkward to consume, which is information the spec authors otherwise don't have.

Documentation fixes, typo PRs, and tightening of error messages are also welcome and small enough to ship the same day.

Contributing¶

The full guide is in CONTRIBUTING.md. The short version:

1. Open an issue first for anything non-trivial. It gives reviewers context and avoids parallel work. For significant or contested changes, that issue is also the first step of the RFC process.
2. Keep changes focused. A schema change, a doc change, and a tooling change are three separate pull requests.

3. Run the project checks locally before pushing:

   just test          # schema generation, Python data model, examples
   just lint          # LinkML schema lint
   just docs-strict   # build docs in strict mode
   

4. Update the docs alongside the schema. Changes to src/astra/schema/*.yaml should also touch docs/specification.md and the relevant tables. The auto-generated schema reference is regenerated by just gen-doc.

Adding schema elements¶

Schema changes follow a small ritual:

# Edit src/astra/schema/{analysis,universe,insight}.yaml

just gen-python    # Regenerate Python datamodels
just gen-doc       # Regenerate the schema reference docs (docs/elements/)
just lint          # Lint the LinkML schema
just test          # Run all tests

Open a PR with the schema, generated artefacts, and any doc updates in a single commit so reviewers see the full picture.

Reporting problems¶

A useful issue includes:

• The version of astra-spec and astra-tools (run astra --version).
• A minimal astra.yaml (or universe file) that reproduces the problem.
• The full error output, copy-pasted from the terminal.
• What you expected to happen instead.

Validation issues are easier to triage when accompanied by a fixture small enough to drop into tests/data/ — usually a single decision and a single output is plenty.

Code of Conduct¶

We expect respectful, thoughtful collaboration in all project spaces — issues, pull requests, and discussions. Treat other contributors the way you would want to be treated; assume good faith; disagree with the idea, not the person. Conduct issues can be raised privately with the maintainers via GitHub.

Citing and license¶

For citation guidance and license details, see the About page.