As a follow-up for this meeting, I think I got this a bit sorted in my head.
The reason I need a specification for blockstack.ts is to stay compatible with the rest of the deployed ecosystem. To do this I started using integration tests that query real endpoints and look whether the library knows what’s returned from there.
I think this way we’d even be able to test compatibility (as discussed in the meeting) without a specification.
Though in my opinion the end goal should stay to have a single place to go to when implementing a new library (which shouldn’t be somewhere in a library).
The steps to take would be:
- Bring every library at a point where all data that entry/leave the service is specified as an interface
(Make sure that these interfaces get updated when the code change) - Gather these interfaces in a single place (for easy discovery)
- Gather these interfaces in a single repository (for even easier discovery)
- Add documentation and informal descriptions to these
Also for versioning: I think that we should try to specify things and then look how frequently these get updated (and we then still can decide on rolling releases vs feature-driven releases).
Regardless I’d happy to have a specification rather sooner than later, because the more projects that (re)use format assumptions made in the code, the harder it gets to clear this up afterwards. The specification surely can be labeled as draft or unstable, but if there’s a single specification, people know where to look and what to do 