I’d like to get a discussion going about what kind of specification we need and how to get it all started. This topic was recently in the engineering meeting where we started discussing this and potential ways to do it.
I feel that this topic still needs to be discussed, also raising it here to keep track of it all.
Currently the relevant parts of the existing specification live scattered around in various repositories (see the other posts for examples ). So for a developer it’s currently not very clear how a library is supposed to interact with the ecosystem.
- Create a coherent and clear specification.
- Enable developers to easily implement libraries in new languages.
- Make sure that the parts implement the specification correctly (make sure that all are on the same page).
- Define a process for changes to the specification, so that future libraries can easily see and react accordingly to these.
My take on this is that there are two different types of specification that we need.
First, specification that defines an interface of a component (“one way”). For example the endpoints Blockstack Core provides. This specification depends heavily on the code of Core and I agree with @aaron that the specification should live next to the code (at least in this case ). The external developer interface of blockstack.js might be also in this category, although I’m not sure whether this needs a full-fledged specification.
Second, specification that defines how multiple parts interact with eachother (“two-way”). For example profiles, which are used by blockstack.js, Core, the explorer, etc. In this case there isn’t a clear owner (in terms of repositories) which should hold the specification. For this I’d like to propose a new repository (probably
If we decide on this, we should make this repository to an entry point for developers who like to implement a new library. So we should explain that there are two kinds of specification, and link all other specifications (e.g. Core endpoints).
During the engineering meeting several caveats came up that are important enough to repeat them here.
Unfortunately I only remember the one that a specification could take away the agility the team currently has.
I think that we might be still in a phase where the ecosystem changes quickly, so changing things in the specification should (for now) be really easy. We probably should mark it as draft or unstable I guess.
For now I’d like to only target the “two-way” specifications (e.g. auth, profiles, zone files, etc).
- Find out where parts are that define these interfaces
- Compare these against eachother to compile one specification from these
- Enforce specification-conformity in the necessary projects
- Create a repository for gathering these
- Add links to other specifications (e.g. the JSON schema specifications for Core endpoints)
- Develop a process for changing the specifications
- Make it easy and fun to develop with these specifications
- Make sure that changes, which affect multiple parts, are made in this specification repository (instead of adding exceptions to multiple repositories)