What do we want in an initial Gloo 0.1 release?

[fitzgen]

I'd like to open this issue to discuss what we want in an initial Gloo release.

We will want to have resolved our plan for versioning Gloo before we actually cut any releases. I think this is the only hard requirement.

We have a spectrum along which to choose: on one end we have "deliver some tiny value to users very soon" and on the other end we have "deliver bigger value to users later".

The more stuff we put in the 0.1 release, the more of a "wow"-factor there is with the amount of things we are shipping, but the longer it will take to be ready. The fewer stuff we put in the 0.1 release, the sooner it starts helping users and we start getting real world feedback on Gloo, but the less of a "wow"-factor the release will have.

---

I propose that we find a subset of the in-flight proposals that we would like to focus on for an 0.1 release. Reach consensus on their designs, get them implemented, and ship an 0.1.

I think this subset should be fairly small and conservative, so we can ship on the sooner end of the spectrum. Because we are doing so much design work up front, the implementation of each proposal is actually a fairly complete API that has more bang for its buck in terms of "wow"-factor and value for users than an equivalently-sized PR otherwise might.

Note that whatever we choose as blockers for the initial release, anything else that lands while we are still trying to finish the blockers would also make it in that 0.1 release too. But those things would be nice-to-haves and we wouldn't delay the release for them.

Here is what I propose as the 0.1 release blockers:

• gloo_timers — already implemented \o/
• gloo_console_timer — already implemented \o/
• gloo_events — already implemented \o/
  • But we still need to have its callbacks take events by reference rather than value (TODO: file an issue for this gloo_event: Take events by reference #82)
• gloo_file — relatively self-contained and I think we are very close to finalizing the design.
• gloo_(properties|reflect) — again, this seems pretty close and there seem to only be two relatively minor open questions about the design still.
• Create a compelling example for the README that uses at least two different Gloo crates together. (TODO: file an issue for this Give the guide some content #81)
• Fill out the Gloo guide mdbook a bit (TODO: file an issue for this Create a compelling example for the README #80)

This list is totally up for discussion and we can add and remove items from it if we want. What do y'all think?

[David-OConnor]

I like it, and propose no changes. It may be tempting to expand this list as more proposals mature, but I'd be happy with (and immediately start using) a release that includes a handful of crates (eg these) that have well-defined uses, and are polished.

[Pauan]

Overall this seems reasonable to me.

The more stuff we put in the 0.1 release, the more of a "wow"-factor there is with the amount of things we are shipping

Is 0.1 a "wow" release? My understanding is that 0.1 is basically the lowest possible version, so it's just saying, "hey, this exists, and it's unstable since it's on 0.x, but play around with it!"

Instead, it would be 1.0 that is the first "wow" release, since that actually promises strict semver semantics.

gloo-file

Just an FYI that I haven't had a deep look at it yet. I plan to do a solid review soon, and I may have some concerns.

gloo-events

Do we want to push #43 for the initial release? EventListener is nice and all, but the casting is pretty ugly, so I think StaticEvent should be the "go-to" idiomatic API instead.

If we release without StaticEvent, users will start to use EventListener, and that will become the dominant way of doing events, even though it's inferior to StaticEvent.

[Pauan]

(Also, as a more general question: should we always release the mid-level and high-level APIs at the same time, or do we think it's acceptable to release the mid-level first, at the risk of it being overused?)

[David-OConnor]

Release each part when it's ready, with a caveat in the readme/docs stating a higher-level API's coming. Also don't care for putting emphasis on a "wow" release of any kind, or considering this when deciding when to make new releases. The main limfac for releases (with new functionality) [should be] making sure the API is something we like and won't want to break soon after.

[rylev]

My only concern is that we don't address DOM manipulation at all (outside of just using raw web_sys calls). I understand that waiting until we have an agreed upon high-level library (e.g., a blessed v-dom implementation like dodrio) might push us back in time too far, but I would expect even the very basic v0.1 to have some way of querying and manipulating the DOM that doesn't require all the type-casting required by web_sys.

I feel similarly about the lack of wrappers around XMLHttpRequest and fetch, but this also makes the likelihood of shipping 0.1 anytime soon much lower.

But I also don't see the need for tying the "wow" blog post with the 0.1 release. We could wait until later to really market the crate.

[Pauan]

@rylev My impression from the OP was that @fitzgen was only considering APIs that are close to ready (he excluded a few that are currently being worked on but aren't ready yet).

An API for manipulating the DOM hasn't even been specced out in a design issue, so it's definitely not close to ready.

Also keep in mind that we can easily add APIs in minor releases, and we can make another "wow" release at 0.2.

[rylev]

I'm focusing more on what makes a release "wow" worthing, and I think as it would stand with the proposed inclusions, it's not very "wow" worthy (without a healthy amount of imagination for future potential). I stand a bit more on the "wait for wow" side of the spectrum @fitzgen alludes to at the beginning of the proposal, but really only when it comes to the question of when to market the crate (e.g., blog posts).

For an actual 0.1 release to crates.io, I'm with @David-OConnor, let's just focus on when the APIs close to completion feel solid enough that we're fairly confident we won't immediately want to introduce breaking changes.

[Pauan]

@rylev I agree, I think the "wow" release should be 1.0, not 0.1

[rylev]

@Pauan Maybe debating if 1.0 should be the "wow" release is out of the scope of this issue, but I disagree. 1.0 should a "wow" release, but there is plenty of utility of having "wow" releases (with marketing pushes) before locking down a complete backwards compat guaranteed API. In other words, I think we should decouple the idea of semver releases and "wow" marketing campaigns.

[Pauan]

1.0 should a "wow" release, but there is plenty of utility of having "wow" releases (with marketing pushes) before locking down a complete backwards compat guaranteed API.

Sure, we can do that, I don't think it's a great idea though.

Having a 1.0 "wow" release says, "this is stable, this is carefully designed and well tested, you can use it to do Real Stuff(tm)!"

Having a 0.1 "wow" release says, "woooo, get hyped, this is fresh, new, shiny, awesome... well, until we break things and your app crashes in production"

Backwards compat does make a difference, since people (especially Rust folks) really like stability. It's a lot easier to get excited about APIs when you know that it is a solid foundation that you can build on top of, and not just some new toy that might break 2 weeks later.

It's the whole reason we've pushed so hard to make Wasm work with stable Rust. It's the whole reason there have been multiple initiatives to push crates to a 1.0 release (even though they were on 0.x for years).

I'm not going to stop us from hyping up the 0.1 release (or 0.2 or 0.3 or...) but I think we should be rather moderate in the hype until we're sure that everything is rock solid (and if it's rock solid, that's the time to do a 1.0 release!)

Basically, my concern is: we hype up the 0.1 release, people come check it out, then things break (or it's so lacking in features that people don't care), people get disillusioned and then leave, never to return. This isn't hypothetical, that exact situation has happened many times, with other projects.

[David-OConnor]

Just try to do the right thing. Who cares what people think?

[Pauan]

Just try to do the right thing. Who cares what people think?

What is "the right thing"? There is disagreement on that.

Also, if we didn't care what people thought, we wouldn't bother with a "wow" release at all, since the whole point of a "wow" release is because we want people to be excited about Gloo and use it in their projects (and hopefully contribute to it as well).

With a large number of people using (and contributing to) Gloo, that ensures the continued survival of the project, and also helps to bring in new perspectives, which results in better APIs (and more APIs).

So we very much so care about what people think (which is after all the whole point of marketing, and marketing is necessary for the success of a new ecosystem).

[fitzgen]

<the role of "wow" in 0.1 initial releases>

Agreed with general sentiment that initial 0.1 releases aren't all about the "wow". It is a nice-to-have IMHO.

I was just trying to lay out the objective trade offs before I introduced my personal opinion on where we should strike a balance on that spectrum ;)

---

@Pauan

(Also, as a more general question: should we always release the mid-level and high-level APIs at the same time, or do we think it's acceptable to release the mid-level first, at the risk of it being overused?)

I think we should be fine releasing the mid-level APIs without having the high-level API there yet. Additions are semver compartible, and we can deliver incrementally better APIs to users, providing value now, and then deliver even better high-level APIs as soon as they're ready after that.

I'm not going to stop us from hyping up the 0.1 release (or 0.2 or 0.3 or...) but I think we should be rather moderate in the hype until we're sure that everything is rock solid (and if it's rock solid, that's the time to do a 1.0 release!)

Basically, my concern is: we hype up the 0.1 release, people come check it out, then things break (or it's so lacking in features that people don't care), people get disillusioned and then leave, never to return. This isn't hypothetical, that exact situation has happened many times, with other projects.

I think the most important aspect in this scenario is to up front and clearly communicate (in release blog posts or TWiRaWA, etc) that while yes there is a lot of cool stuff in this 0.X and you should be excited about it, we are still early days and things will likely shake up a bit in future releases.

---

To bring things back to the concrete discussion at hand: does anyone have any suggested additions/removals to the proposed 0.1 blockers?

@rylev mentioned xhr/fetch and dom manipulation. Personally, I don't think we should consider anything that is not in-flight right now (eg dom manipulation) because I'd rather ship sooner. However, we do have an in-flight mid-level XHR design that we could potentially add as a blocker. What do folks think of adding that? If we add that, do we want to remove something else?

[anderejd]

In other words, I think we should decouple the idea of semver releases and "wow" marketing campaigns.

This resonates with my thinking for most marketing and semver discussions. Please keep marketing and semver versions decoupled. A marketing push can be done at any release and can present features and bugfixes from many semver releases.

Hi BTW, I'm very much looking forward to using gloo and perhaps contributing if I find the time :) The goals of gloo seems like what I want as a foundation for building pure Rust single page web applications.

My 0.1 wishlist

Wrappers, hiding all JsValue types for:

• XmlHttpRequest ([WIP] Add mid-level bindings for XmlHttpRequest #44). Fetch can come later.
• DOM manipulation. Partial API coverage would be fine in 0.1, imho.

My use case doesn't need virtual DOM, just simple direct access, short-term at least.

[Pauan]

In the interest of shipping ASAP, I propose the following list of crates:

• gloo_timers
• gloo_console_timer
• gloo_events
• gloo_file

The only one not implemented is gloo_file, but the RFC for it was accepted, and it seems fairly self-contained, so I think it's okay to wait for it.

Keep in mind that it's easy to add new APIs in a 0.1.1 release, or a 0.1.2 release, etc.

So there's nothing stopping us from making rapid point releases after the initial release.

[fitzgen]

In the interest of shipping ASAP, I propose the following list of crates:

[...]

Keep in mind that it's easy to add new APIs in a 0.1.1 release, or a 0.1.2 release, etc.

So there's nothing stopping us from making rapid point releases after the initial release.

That sounds good to me, and the latter point is a good one. Adding new APIs is easy to do, changing existing ones is much harder. As long as we are happy with what we commit to shipping, we should be good for rapid releases that add new stuff.

I'll create a milestone that we can rally around, implement, and publish a 0.1 release.

[fitzgen]

Ok, I am going to close this issue, and we can use this milestone to track the 0.1 release: https://github.com/rustwasm/gloo/milestone/1

Thanks for the discussion everyone!