@scmwiz and others have proposed an API beta testing phase with constant changes happening to the interface. We’ll document the changes but that means your “beta” plugins will break all the time.
The alternative is to try to design the interface out in the open, and we just imagine what we would need for our plugin ideas.
Personally we would prefer the former method, since we believe it’s hard to know exactly what you want just by imagining instead of doing real development.
What do you guys think? Anyone willing to test develop for an unstable interface? Our choice will depend on what developers would do – if most of you want to develop only after v1.0, we probably can’t do much beta testing, other than maybe trying to write a few third party plugins ourselves.
Beta testing with a constantly evolving API is a real beta test.
As long as anyone that has installed possible broken plugins will not cause Obsidian to crash at startup and there’s an easy way to disable/remove such plugins in the UI.
Let developers develop for the interface. Put a big disclaimer that the interface can change. Just like has been said need to ensure there is a simple way to disable plugins without obsidian becoming unusable.
I would also like to add another consideration for API development. Need a way to ensure that plugins don’t auto-update. Let people decide when they want to update. I have heard about Google Chrome extensions which were good but then silently someone updated to add malicious code in it. Auto-update allowed the malicious code to spread across many browsers. So think security. People are putting their notes in offline vault for privacy reasons among others. One incident like that can cause trust to fall.
An evolving API would be easier to deal with provided there is documentation + may be an example plugin that exercises the API. It would also be good if a warning can be provided (ex: “we are thinking of changing this function this way in the next release”). Even better would be if there is an opportunity to discuss and refine a proposed API function before it is baked in.
Stiil, I would assume a broken plugin or API can crash obsidian any time - including wiping out the vault.
@anshbansal makes a good point about auto-updating plugins. Even aside from the security thing, it’s good to know what you’re updating to and what possible incompatibilities there may be. Perhaps reading tags from public github repos would be a good start (similar to what you’re doing with themes, but only updating on release tags).
@ksandvik Also makes a good point about including a simple, user-friendly safe mode for disabling all plugins - so you can selectively re-enable them and see which one broke everything
Oh interesting, like an “experimental” or “unstable” flag.
Yeah, which is why we should probably just all dogfood our plugins instead of letting non-developers use it. Or put a huge red banner to let them know they must back up their data if using beta plugins.
One thing I would appreciate is having the documentation be clear about the stability level of each API call. e.g. have some API calls marked as experimental, which are extremely prone to being changed or removed, alpha, which can be changed or removed but with a little bit more caution, beta which wouldn’t be changed or removed without a deprecation period, and stable which is core and won’t change without a major version change.
I’m totally happy if 100% of the API endpoints are in the experimental phase at the beginning of the public API, but it’s nice to see which APIs are progressing towards stability over time, and which remain totally experimental.
@Silver I would vote for bringing in beta testers early, but with the caveat that you limit the number of people who have access. Perhaps stage it like you did with the app, bringing in a few more devs every week or something like that. I wouldn’t want the Obsidian devs to get overwhelmed with feedback and requests and plugins. You could have a short application form where the prospective dev describes the first plugin they want to create, and then you can select for a variety of plugin types. At this early stage, I might suggest the process be more about hammering out the API and less about creating finished, polished plugins for deployment to the wider community.
Re: @anshbansal and auto-updating, WordPress might be a good model. Users have to manually update all plugins, and plugins have to report what minimum version of the app they are compatible with. WordPress also forces a minimum PHP version, which may not be necessary with JavaScript/TypeScript and compilers.
Disabling all plugins = maintenance mode
Second @ksandvik on building the API in TypeScript. Have you considered what kind of documentation tooling you are going to use?
We do everything in TypeScript internally, so it should be pretty easy to release the definition files too. For developers who don’t use TypeScript, they can just skip it.
I am very okay with unstable API. I think it is also a better solution in the long term: it is impossible to stabilize and API without people trying to use them in the most absurd possible ways.
Throwing my hat in the ring for unstable API. Everyone above has pretty much covered my thoughts, so I don’t have much to add. But the sooner we can do anything, even if it breaks, the sooner we know what’s possible or not.
Unless you guys want to support multiple API versons. For example, v0.1, v0.2, v0.3, etc. Developers can specify which version they’re working with. Then perhaps depricate all old APIs at once. That way, things aren’t constantly breaking, but only breaking in batches every few months.
Personally I think it’s better to break the API and force plugin fixing/changes especially as end users will not freeze their Obsidian version, they just happily update. Keeping old APIs around for backwards compatibility just adds more cycles to maintain those rather than using the engineering resources fixing new APIs and features.
