search

PerlDancer / Dancer2

Perl Dancer Next Generation (rewrite of Perl Dancer)
http://perldancer.org/
Other
542 stars 274 forks source link

Define the Dancer2 Deprecation Policy #1635

Closed cromedome closed 2 years ago

cromedome commented 2 years ago

This has been needed for some time. We need a formal deprecation policy.

There are a lot of reasons for this, but it comes down to it being a good practice, and I feel as a popular framework it's our responsibility as maintainers to have such a policy in place to help us grow and evolve the framework in the most healthy way possible. To that end, I am posting a draft of the deprecation policy that the core team is considering, and I welcome everyone (including the core team!) to make more suggestions as to what this should look like, to ask questions, and to bring to our attention concerns and problems we may not have considered.

This replaces an earlier discussion (#743) - I have linked it for convenience.

I'll let this discussion continue for a while before we pull the trigger and adopt this with public feedback and consideration. Thanks for your thoughtful review and feedback on this.

Deprecation Policy

Defining Deprecated Code

While there are conflicting ideas about deprecation, in Dancer2, deprecated code is code that:

Deprecated code is code we either had to write and can now remove or we thought was a good idea and were wrong. It is code that doesn't overall benefit users or the developers.

Deprecated code is code that is marked for eventual removal and we do not intend to keep in the Dancer2 codebase.

Deprecation process

Deprecated code is marked with warnings and the version and/or date in which it will no longer be available.

Public Notice

When a feature/code is to be deprecated, the Dancer Core Team will create a new GitHub issue for the code/feature to be deprecated, and announce this in a public manner (blog post, Twitter, and the mailing list, at minimum). The notice should provide the reason for the deprecation, what Dancer2/the community is gaining as a result of the deprecation, and what the officially recognized alternative to the deprecated code is.

The public notice period will provide the developer/user base an opportunity to voice objections or provide feedback or alternatives to deprecation. It also allows the Core Team to better assess the potential long range effects of deprecation.

While the deprecated feature/code can be discussed by community, the decision will be ultimately made by the Dancer Core Team. There is no definitive time for the public notice period to end; some deprecations are more urgent than others, and each situation is left to the discretion of the Core Team, with feedback from the community.

Soft Deprecation

When code is soft deprecated, a warning will be thrown to indicate that the code is to be considered deprecated. Apps will continue to function normally otherwise.

Hard Deprecation

After 12 months or two major releases (whichever comes first), the code is considered to be hard deprecated. An error will continue to be thrown, but unlike soft deprecation, continued usage of the deprecated code will cause the application to die.

There is one caveat to this: code will never be deprecated for less than 6 months. So if we deprecate code after v0.500000, become unusually productive, and produce Dancer 0.600000 and 0.700000 in a two month timeframe, no deprecated code will be removed because 6 months hasn't elapsed.

Removal

Six months following hard deprecation, or one major release after hard deprecation, the deprecated code is removed from Dancer2.

Exceptions

In special cases, based on community feedback, these timelines may be extended. But we expect this to be a rare occurrence, at best.

Plugins

We strongly encourage (but cannot/do not require) plugin authors to adopt the same policy.

GeekRuthie commented 2 years ago

This seems to me like a sane, rational approach to deprecation, that will have every opportunity to minimize pain points for Dancer2 app developers as well as the team. FWIW, two thumbs up.

My only suggestion is that this policy be explicitly extended in a way that says the Core Team expects/requests plugin developers to follow similar behavior--soft deprecation, then hard deprecation, then removal. Nothing much you can do to require it, of course, but as a plugin developer myself, having some clear knowledge of the expectations the Core Team has of me would be nice, particularly in the areas where my plugins have interaction with core code.

abeverley commented 2 years ago

Hi Jason, thanks for tackling this! My only thought is around the timelines: 12 months doesn't seem that long for soft-deprecation, and then with only 6 months before the code is removed it's quite likely that someone will upgrade (e.g. after 2 years) and then find a function completely missing. As a compromise, maybe the timelines could remain as they are, but with a desire for them to be longer if possible?

Also a minor point, rather than publication in either/or GH issue / mailing list, maybe it could always be both?

racke commented 2 years ago

A GH issue is inevitable for the deprecation, but the public note might start before that to get feedback before actually writing code for it. @abeverley I agree with you, most users won't get a notification about new GH issues.

@cromedome: Deprecated code is code that is marked for eventual removal and we do not intend to keep the Dancer2 codebase.

Sounds like we throw away the Dancer2 code base :smiling_imp: .

Deprecated code is code that is marked for eventual removal and which we do not intend to keep in the Dancer2 codebase.

xsawyerx commented 2 years ago

This sounds good to me.

Regarding timelines raised by @abeverley, I think it's fair to allow discussions on certain deprecations to possibly take longer. What should be kept in mind is that with exact timelines (2 releases or X number of months), there's a consistent expectation. When timelines drift (on purpose or accidental), this might be considered reliable anymore and the expectation people have might drift as well. Just a point for thought.

Regarding plugin authors' policies raised by @GeekRuthie, I think "the expectations the Core Team has of me" is difficult to express in terms of "we expect you to..." Maybe we should try "We promote you to" or "We strongly encourage you to adopt the same policy"? What do you think?

I think it would be great to create a communication channel with plugin developers in general. Something we wanted to do in the past was to maintain a list of which plugins work with a current version or not, but this was a lot to take on. We can, however, commit to communicating with plugin developers if/when we find that a deprecated feature is used in their code and request that they make it clear to their users of such changes. (Then again, not all plugin authors have communication channels with their users.)

One additional idea (that was half-implemented) was a Perl Critic policy that warns you when it detects deprecated syntax and suggests how to approach fixing it. (Though this probably shouldn't be in the policy.)

Nice grammar correction by @racke. :)

GeekRuthie commented 2 years ago

"Strong encouragement" is kind of what I had in mind there, @xsawyerx, and I like the way you worded that.

I would love to have more-open channels for communication with plugin devs,as well. As for your testing idea, it seems to me that a customized subset of a cpan-testing rig might do the trick. I have fiddled around with testing a bit, but perhaps someone with more testing chops could undertake that. The results matrix could be attached to the Dancer website, maybe.

...and I've taken your prior work and am working on a Critic policy in my less-busy moments. :)

cromedome commented 2 years ago

@cromedome: Deprecated code is code that is marked for eventual removal and we do not intend to keep the Dancer2 codebase.

Sounds like we throw away the Dancer2 code base smiling_imp .

Nice catch, thanks!

cromedome commented 2 years ago

I think it would be great to create a communication channel with plugin developers in general. Something we wanted to do in the past was to maintain a list of which plugins work with a current version or not, but this was a lot to take on. We can, however, commit to communicating with plugin developers if/when we find that a deprecated feature is used in their code and request that they make it clear to their users of such changes. (Then again, not all plugin authors have communication channels with their users.)

I like the idea of creating plugin-authors@perldancer.org (or whatever) with whatever information we can farm from MetaCPAN and create a low-traffic list for authors of existing plugins. We could also farm the list of plugins and authors, add them to the GH wiki if there is any additional metadata we'd like to keep tabs on. If we think these are good ideas, I'll create another issue for it.

cromedome commented 2 years ago

Hi Jason, thanks for tackling this! My only thought is around the timelines: 12 months doesn't seem that long for soft-deprecation, and then with only 6 months before the code is removed it's quite likely that someone will upgrade (e.g. after 2 years) and then find a function completely missing. As a compromise, maybe the timelines could remain as they are, but with a desire for them to be longer if possible?

In consideration of this, and taking @xsawyerx's suggestion into account, I created an Exceptions section that mentions that yes, we can break the rules if there is a good reason to do so. We don't plan to bend the rules, but we also acknowledge that sometimes there are good reasons to.

Also a minor point, rather than publication in either/or GH issue / mailing list, maybe it could always be both?

I changed the wording to reflect this. This was an excellent point. An issue will always be created, and some other form of public announcement will be made as well. Thank you for this suggestion.

cromedome commented 2 years ago

This is an excellent discussion, and I love how this is taking shape with all of the great feedback!

xsawyerx commented 2 years ago

I think it would be great to create a communication channel with plugin developers in general. Something we wanted to do in the past was to maintain a list of which plugins work with a current version or not, but this was a lot to take on. We can, however, commit to communicating with plugin developers if/when we find that a deprecated feature is used in their code and request that they make it clear to their users of such changes. (Then again, not all plugin authors have communication channels with their users.)

I like the idea of creating plugin-authors@perldancer.org (or whatever) with whatever information we can farm from MetaCPAN and create a low-traffic list for authors of existing plugins. We could also farm the list of plugins and authors, add them to the GH wiki if there is any additional metadata we'd like to keep tabs on. If we think these are good ideas, I'll create another issue for it.

I think there is a possible practicality issue here. Maintaining such a list requires an entire subscribe/unsubscribe process, as well as getting consent for the initial list. (I wouldn't appreciate being added to a list - even one that helps me - without knowing about it and approving ahead of time.) This is not to mention the hosting and maintenance of the list itself, even we're not going with something like Google Groups or Topicbox (which we should if we intend to do this). We don't yet know how utilized it would be.

While having a list can provide a place to discuss this, I suggest something different:

This allows keeping the maintenance to a script that does not need updates (except an exception list of emails that do not work anymore or authors who abandoned their modules) and utilizes the existing available list to discuss it.

This also allows us to see any influx of communication and determine whether a dedicated communication channel is necessary. This can also be Slack, for example. (Despite my dislike of Slack, people do utilize it heavily for support channels.)

bigpresh commented 2 years ago

With regards to hosting & maintaining a mailing list, that's not a problem - I already run Mailman lists for dancer-users and dancer-dev, so adding another if we want to is not a problem at all. Grabbing all maintainers of plugins from MetaCPAN could be used to send invitations to join the list from time to time, but I'm not sure we'd want to use that every time we want to send an update, at least not without then having to run some kind of unsubscribe management system too for anyone who says "please stop sending me these".

Slack is alright, but requires active checking; an ML subscription can stay in the background doing nothing for years, then alert you when a mail turns up.

xsawyerx commented 2 years ago

The goal in mind for my suggestion is to first validate the value of it before creating lists to subscribe/unsubscribe/maintain or Slack channels for synchronous support. We already have a mailing list at the moment and we just send emails for notification of major changes. If see it's valuable and there's a growing need, we can expand with a separate list.

cromedome commented 2 years ago

@abeverley Just wanted to check and see if the changes I outlined above takes care of your concerns. Thank you for taking the time to provide your feedback!

abeverley commented 2 years ago

Sorry for the slow reply @cromedome and thanks for the tweaks. I'm happy to go along with the proposed wording, although I think that maybe code removal period could be a bit longer, so that at least someone who upgrades after a couple of years is informed why there code is no longer working, rather than just finding that methods no longer exist (not the end of the world, just my tuppence worth!)

cromedome commented 2 years ago

I am good with 12 months soft-deprecation and 12-month hard deprecation. That's two years from the announcement until it gets removed. I've been fortunate to (mostly) write Perl in places that try to stay as current as possible, so I haven't had to think much about updating only every few years. I can imagine being a bit frustrated if I did an update and suddenly things broke without and there is little to help me figure out why.

@abeverley - does that seem a bit more helpful? @xsawyerx, @racke, @bigpresh, @GeekRuthie - any thoughts to share?

Thanks all!

abeverley commented 2 years ago

Thanks Jason, sounds great to me.

racke commented 2 years ago

Yes, two years are enough. :+1:

cromedome commented 2 years ago

Considering this resolved. Including this as part of the Dancer2 0.400000 release. Which starts today.