Discussion: Developer/Strongloop communication

[doublemarked]

At the advice of @bajtos in #2693 I am opening this discussion regarding developer communication.

Context: Fixes #2693 and #3021 implemented access-token invalidation when the users changes an email or a password. However, the current code deletes all access tokens, including the token used to make the change password/email request. The effect of this is that client code must anticipate immediate token invalidation any time it submits changes to a user's email and password, which is notable behavior change to be slipped into a point release.

I'd like to propose several questions associated with this. These questions are fielded to both the Strongloop team and the developer community,

1. Under what conditions do we consider it acceptable to introduce breaking changes into a minor release?
2. What is the best way in which the Strongloop team can communicate to the developer community when such changes are upcoming?

Tasks

• Setup a low-volume Announcement mailing list - see https://groups.google.com/forum/#!forum/loopbackjs-announcements
• Update loopback.io documentation - Link to Announcements list in top navigation loopbackio/loopback.io#316
• Update README in this repository - see README: add a link to our announcements list #3261

[doublemarked]

I'd like to share my own thoughts on this. I may have missed it, but I don't recall any communication regarding these changes, which I think took place in mid-September. Our team did not discover the problem until last week when we performed some cleanup that bumped up the Loopback version.

I would like to offer the following suggestions,

1. Perhaps Strongloop should consider a low-volume announcement-only Google Group that is used for important developer alerts/notifications (security notices, breaking changes, notable releases, etc). The general Google Group has a lot of chatter and I would not be surprised if many developers do not subscribe or ignore it.

2. Similarly, perhaps the Github release notes for 2.35.0 should have emphasized the breaking changes.

3. Might it have been been more appropriate to include these changes only with configuration that allows it to be disabled, even if it defaults to on?

[superkhau]

@doublemarked Thanks for bringing up this discussion. I've been advocating a Community Governance page on loopback.io for things like this (and transparency especially). @bajtos Has something in the backlog (probably won't get to it till the new year though since most people are going on vacation soon).

IMO:

Under what conditions do we consider it acceptable to introduce breaking changes into a minor release?

Never since we should be following semver and only breaking on majors.

What is the best way in which the Strongloop team can communicate to the developer community when such changes are upcoming?

Google Groups needs to be first and foremost our annoucement channel (in addition to blog posts/tweets). I brought up some discussions in the past and loopback-announce was debated (no action taken yet).

Similarly, perhaps the Github release notes for 2.35.0 should have emphasized the breaking changes.

I didn't follow the discussion above, but it should've never broken in the first place. That said, I think the better question is what do we do when accidentally releasing breaking changes in minor/patch versions. Do you have any suggestions for this? Maybe doing another subsequent minor/patch to revert the change as soon as reported?

Might it have been been more appropriate to include these changes only with configuration that allows it to be disabled, even if it defaults to on?

The policy should be to default to the state it was previously at to prevent breaking changes (and force users to manually turn on the feature flag) -- this is not officially documented, but I propose we set this as a ground rule.

[doublemarked]

Never since we should be following semver and only breaking on majors.

Yeah, indeed. I have taken a cautious tone because it's not clear whether anybody agrees with me that token invalidation is a breaking feature, but I certainly agree with following semver.

I didn't follow the discussion above, but IMO it should've never broken in the first place. That said, I think the better question is what do we do when accidentally releasing breaking changes in minor/patch versions. Do you have any suggestions for this? Maybe doing another subsequent minor/patch to revert the change as soon as reported?

Yes I think a patch that reverts the change (or introduces a default-off flag) would be correct. It should be treated with similar severity to a regression.

The policy should be to default to the state it was previously at to prevent breaking changes (and force users to manually turn on the feature flag) -- this is not officially documented, but I propose we set this as a ground rule.

Sounds good to me.

[bajtos]

Hi, thank you @doublemarked for starting this discussion.

Under what conditions do we consider it acceptable to introduce breaking changes into a minor release?

I agree with what @superkhau wrote, we shouldn't be introducing breaking changes into minor versions.

In the particular case you have described (access-token invalidation), we did not realise this change may be breaking existing applications :( To be honest, this seems like a problem that cannot be fixed - how to know what we don't know? The best we can do is to limit the impact of changes like this one.

Yes I think a patch that reverts the change (or introduces a default-off flag) would be correct. It should be treated with similar severity to a regression.

I like the idea of using feature flags and changing their default value to quickly enable/disable the feature if needed 👍

Perhaps Strongloop should consider a low-volume announcement-only Google Group that is used for important developer alerts/notifications (security notices, breaking changes, notable releases, etc). The general Google Group has a lot of chatter and I would not be surprised if many developers do not subscribe or ignore it.

+1 ✖️ 💯 from me.

[superkhau]

tldr;

• Create loopback-announce GG for low-volume announcements (2 points)
• Feature flags to enable/disable features (breaking changes) that were accidentally introduced in non-major versions (2 points to describe on community governance page)
• Community governance page to describe such processes for transparency (3 points)

We'll need to create issues to take these items on in the new year (or whenever we decide to prioritize these issues as part of sprint planning).

• Open PR in loopback.io to add information about the new GG and feature flags to the loopback.io site -- ping @crandmck for review (3 points)

cc @bajtos

[superkhau]

Slapping high level 13 point estimate for @ritch to prioritize during backlog grooming.

[doublemarked]

All sounds great, guys. TYVM!

[crandmck]

Please also open a PR in loopback.io to add information about for the new GG and feature flags to the loopback.io site. If unsure where or how to do so, open an issue in the loopback.io repo and I will help.

[superkhau]

@crandmck Updated bullet list to include tasks from your comments. TY for chiming in.

[bajtos]

Let's work in smaller incremental steps here. I created #3257 to track the documentation about feature flags.

I'd like to keep the scope of this item only as the Announcements Google Group together with necessary loopback.io changes.

[bajtos]

The new mailing list: https://groups.google.com/forum/#!forum/loopbackjs-announcements

[doublemarked]

Great. Hmm, however @bajtos that group does not appear public?

EDIT: Ok now it does! Looks good.

[bajtos]

I configured the Google Group permissions to allow anybody to subscribe to this mailing list, but also to restrict new posts to administrators only. We can tweak these settings in the future as needed.

[bajtos]

Announcement post in LoopBackJS group: https://groups.google.com/forum/#!topic/loopbackjs/qvMC6r2IRwo

[bajtos]

Done.