Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

✨ ub-needs-exchange: the later slices — the writer, format_version writing, the shims, the ingest layer, ub-test-reports

Open
  • Is something wrong?
#2,233 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
8/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
python
Domain
data

Research direction

This is a multi-slice plan, not a single change, and the plan itself lives in ubcode-orchestration/fable/exchange-handover.md, which is not in this repository. Start by reading tests/test_exchange_readers.py to see the reader cases the ingest slice would cover, then find NeedsList and generate_needs_schema in the sphinx-needs source. Done means a maintainer has agreed the first slice's scope, since each slice is its own pull request and review.

Written by the indexing model from the issue text.

Description

enhancement pkg: ub-needs-exchange

Slice 1 of the needs.json library shipped the reader, the contract and the document-layer corpus (#2219, 1.0.0), and sphinx-needs reading through it (#2229). The plan's remaining slices, in order:

  1. The writer: NeedsList (minus env), generate_needs_schema and the needsfile.json shape move into the package; the contract gains the writing half (today §10 describes only the value serialisation the hash derive kind depends on).
  2. format_version writing in both writers (sphinx-needs' and ub-test-reports' envelope writer), so a reader can tell a file's format; the reader already accepts the key.
  3. The shims: sphinx_needs.needsfile and whatever needimport / needs_external_needs keep importing by the old names, as deprecated aliases like sphinx_needs.exchange (removal at 10.0 for all of them).
  4. The ingest layer of the corpus: what each tool's readers decide of a record (id_prefix, :ids:, :filter:, :tags:, coercion, the ten-field table) — the cases from tests/test_exchange_readers.py and the review's constructions; the header already defines layer = "ingest", reader and the skip rule, and says the slice defines its own keys (project, the skip classes).
  5. ub-test-reports' adoption of the writer.

Each slice is its own pull request with its own review. The record of the plan is ubcode-orchestration/fable/exchange-handover.md §5 (not in this repository).

Dominant language
Python
Stars
309
Forks
103
Avg merge
11h 26m
Merged PRs (30d)
118

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from useblocks/sphinx-needs

All issues in useblocks/sphinx-needs

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.