원문 안내

아래 내용은 저장소 루트의 CONTRIBUTING.md를 그대로 렌더링한 것입니다(영어). 이어지는 "적합성, 실제로는" 절은 이 사이트에만 있는 보충 설명입니다.

Contributing¶

Thanks for helping! The one thing to understand about this repository: the product is a bit-exact cross-language mapping. Everything below follows from that.

Ground rules¶

SPEC.md is normative. Code follows the spec, never the other way around. If an implementation and the spec disagree, the implementation is wrong (or the spec needs an RFC — open an issue first).
Any change that alters encode output or decode acceptance is a new format version, not a patch. Format v1 outputs are frozen forever.
An implementation is conformant iff it passes the files in testvectors/:
ff1_nist.json — the official NIST FF1 samples (validates the FF1 core),
v1.json — dealcode vectors (validates the full codec). This covers every section: vectors, invalid_codes, normalize, range_counters, and the top-level invalid_configs (see SPEC.md §9 for the exact obligations of each),
v1c.json — fixed-length cycling mode vectors (SPEC.md §11), required for implementations that ship the mode; all seven here do.

Working on an implementation¶

Each directory (python/, js/, go/, java/, rust/, c/, cpp/) is a self-contained, idiomatically packaged library. Its README shows how to run its tests. Shared expectations:

No new runtime dependencies. AES/SHA-256 come from the platform's standard or designated crypto library only.
Public APIs stay small and mirrored across languages: construct a codec (key, alphabet, min/max length, domain) → encode / decode → three error kinds (config / range / invalid code).
Codecs are immutable and safe for concurrent use.

Changing the spec or vectors¶

Open an issue describing the change and its compatibility impact.
Spec text, the Python reference (python/), regenerated vectors (python3 scripts/generate_test_vectors.py), and updates to all implementations land in a single PR.
Output-affecting changes bump the format version (new tweak prefix dealcode/v2/...) and add new vector files next to the old ones — v1 vectors are never edited.

Adding a new language¶

Port from SPEC.md alone (peeking at python/ is fine), make both vector files pass in your test suite, add a README with a quickstart and a database recipe, and wire a job into .github/workflows/ci.yml (including the new name in the only input's options list). That's the whole bar.

Branches & merging¶

Trunk-based: main is always releasable and is protected against force-push and deletion; release tags (v*, go/v*) are immutable. Contribute from a fork/feature branch via PR — squash-merged, branch auto-deleted. Versions are SemVer, released in lock-step across all seven packages (see RELEASING). Dependabot patch/minor updates auto-merge once CI passes; majors wait for a human.

CI¶

CI runs automatically on every push to main and on every pull request (all seven implementations plus a vectors-reproducibility check). Please still run your language's suite locally before pushing — it's faster feedback than the runners. gh workflow run ci.yml -f only=<job> remains available for one-off manual runs of a single job.

Releasing (maintainers)¶

Registry publishing is automated per registry via the publish-*.yml workflows; the full checklist, the credential/Trusted-Publisher inventory, and hard-won bootstrap notes live in RELEASING.md.

License¶

MIT. By contributing you agree your contribution is MIT-licensed.

적합성, 실제로는¶

"이 구현은 올바르다"의 기준은 의도적으로 기계적입니다: testvectors/의 파일들을 통과하면 됩니다 (v1c.json은 고정 길이 순환 모드용으로, 이 모드를 제공하는 구현에 필수입니다 — 여기 7개 구현 전부 해당).

ff1_nist.json은 dealcode 자체 레이어와 무관하게 FF1 코어를 NIST 공식 샘플 벡터 9개에 고정합니다. FF1이 맞으면 통과하고, 통과하면 서로 다른 7개 FF1 구현이 같은 순열을 계산한다는 것이 증명됩니다. (NIST 간행물은 미국 퍼블릭 도메인입니다.)

v1.json은 코덱 전체를 검사합니다: 모든 프리셋 알파벳, 스테이지 경계(코드가 한 글자 자라는 정확한 카운터), 두 가지 키 파생 경로(AES 크기 바이트는 직접 사용 vs 나머지는 파생), 디코드 정규화(hex 대소문자, Crockford O→0, I/L→1), 도메인, 그리고 반드시 거절되어야 하는 코드들 — 잘못된 길이, 잘못된 문자셋, 스테이지 밖, 카운터 공간 밖. scripts/generate_test_vectors.py가 Python 레퍼런스 구현으로부터 생성하며 카운터는 2^53을 넘기 때문에 JSON 문자열로 인코딩됩니다.

모든 언어의 테스트 스위트가 두 파일을 소비하므로 포팅은 스위트가 초록이 되는 순간 적합합니다 — 판단이 개입할 여지가 없습니다. v1 벡터가 영원히 동결되는 이유이기도 합니다: 이 벡터가 곧 구현들 사이의, 그리고 여러분과 이미 발급된 모든 코드 사이의 호환성 계약입니다.