Share one payjoin concept description across READMEs - #1864
Conversation
Coverage Report for CI Build 34614336532Coverage remained the same at 86.646%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsNo coverage regressions found. Coverage Stats
💛 - Coveralls |
9726804 to
ee3e3ac
Compare
benalleng
left a comment
benalleng
left a comment
There was a problem hiding this comment.
CACK Make sure to take out Claude co-authorship from your commits please
caarloshenriq
left a comment
caarloshenriq
left a comment
There was a problem hiding this comment.
Concept ACK
+1 on @benalleng's point to drop Co-Authored-By from the commits. Also worth dropping the Claude-Session: trailer on both commits while rebasing
spacebear21
left a comment
spacebear21
left a comment
There was a problem hiding this comment.
This seems like a lot of plumbing for READMEs, couldn't we just link to the payjoin.org site or the BIPs directly in each README file?
Yeah, initially made me think if there's a better way to manage all package descriptions 🤔 We could just copy paste once and remember to synchronize the descriptions with the bip content too |
ee3e3ac to
7ede940
Compare
| These bindings implement both | ||
| [BIP 78](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki) | ||
| (synchronous payjoin) and | ||
| [BIP 77](https://github.com/bitcoin/bips/blob/master/bip-0077.md) | ||
| (asynchronous payjoin, where sender and receiver exchange the transaction | ||
| through an untrusted directory and never need to be online at the same |
There was a problem hiding this comment.
Prefer to use the titles of the BIPs "Simple Payjoin" and "Async Payjoin"
Package READMEs each describe payjoin in their own words and the descriptions drift apart; a correction to one does not correct the others (payjoin#1772). Keep the conceptual text in one file, payjoin-ffi/CONCEPT.md, with a script that copies it into a marked block of each README and a --check mode that reports drift. The text follows the BIP 77 abstract's framing preferred in the review of payjoin#1764: senders and receivers interact to make batched transactions, with the privacy consequence stated as preserving privacy by poisoning the common-input-ownership heuristic, and it links the BIPs by their titles, Simple Payjoin and Async Payjoin.
Insert the synced concept block into the python, dart, javascript and C# package READMEs and the top-level payjoin-ffi README, all generated by payjoin-ffi/contrib/sync-concept.sh. The C# README's paragraph is replaced by the shared block, keeping its native-libraries note as C#-specific text, and the top-level mission paragraph is replaced likewise.
I dropped the heavier CI drift checks, the light script is what's left |
7ede940 to
b35c0a7
Compare
6 participants
Closes #1772.
Keeps the conceptual description of payjoin in one file,
payjoin-ffi/CONCEPT.md, and copies it into a marked block of each package README (python, dart, javascript, C#) plus the top-levelpayjoin-ffi/README.md, replacing the per-package variants that had already drifted (only the C# README carried the full paragraph; the others had none, and the top-level README had a third wording).Since every registry (PyPI
readme=, NuGetPackageReadmeFile, npm, pub.dev) publishes the checked-inREADME.mdas-is, the text is materialized rather than referenced:payjoin-ffi/contrib/sync-concept.shrewrites the block between<!-- concept:begin … -->/<!-- concept:end -->markers, and its--checkmode reports drift fromCONCEPT.mdfor anyone who wants to verify (not wired into CI, per review). The sync output is a fixpoint withnix fmt(prettier's blank-line padding around HTML comments is emitted by the script).Wording follows the issue's three parts and the framing pinned in the #1764 review: it opens with the BIP 77 abstract sentence ("Payjoin lets Bitcoin senders and receivers interact to make batched transactions"), states the privacy consequence as preserving privacy by poisoning the common-input-ownership heuristic, and points to BIP 78, BIP 77, and payjoindevkit.org. The C# README keeps its native-libraries note as language-specific text outside the block. The draft C++ bindings (#1827) can adopt the same block when they land.
Disclosure: co-authored by Claude Fable