Consistently name methods that turn into another more complete type

[pitdicker]

Consistently name methods that turn into another more complete type

[djc]

Okay, well, let's skip 0.4.x for now then.

[djc]

We can also rename them all to with_*. However we have 26 methods that currently follow a convention that with_ keeps the type the same and modifies some component of the date/time. It seems nice to maintain a distinction.

Hmmm, not sure I want to overindex on maintaining this distinction? It's one factor, but not sure how important it should be.

Can you add another table that with these with_ methods to we can compare?

[pitdicker]

Those would be:

NaiveDate::with_year
NaiveDate::with_month
NaiveDate::with_day
NaiveDate::with_ordinal

NaiveTime::with_hour
NaiveTime::with_minute
NaiveTime::with_second
NaiveTime::with_nanosecond

NaiveDateTime::with_year
NaiveDateTime::with_month
NaiveDateTime::with_day
NaiveDateTime::with_ordinal
NaiveDateTime::with_hour
NaiveDateTime::with_minute
NaiveDateTime::with_second
NaiveDateTime::with_nanosecond

DateTime::with_year
DateTime::with_month
DateTime::with_day
DateTime::with_ordinal
DateTime::with_time
DateTime::with_hour
DateTime::with_minute
DateTime::with_second
DateTime::with_nanosecond
DateTime::with_timezone

Time-rs uses replace_ for most of these.

[djc]

Okay, I think it sounds good to stick with with_ for same-type and use at_/in_ for different-type. Let's introduce the new names on main with deprecations?

[pitdicker]

Wow, that is a fast decision 😄. But I think it is going to be a nice improvement.

Let's introduce the new names on main with deprecations?

Those deprecations are going to hit everyone who uses chrono. I am afraid at some point we are going to chaise users away if we keep causing too much churn.

[djc]

I mean, it will still be churn if we change them only in 0.5, except that will be a lot more churn all at the same time? Better to smooth it out over time (and give us a chance to get feedback on the change), IMO. Maybe we can split these changes out?

BTW I do kind of like the assume_ prefixes from time-rs because they IMO more clearly/explicitly convey the intended semantics. So maybe we should copy those instead of in_()?

[pitdicker]

I mean, it will still be churn if we change them only in 0.5, except that will be a lot more churn all at the same time? Better to smooth it out over time (and give us a chance to get feedback on the change), IMO.

I can't deny it is going to have to happen at some point. And from our perspective doing it on the 0.4 branch brings advantages.

But I really do think there is a limit to what at least a portion of our users will tolerate. And I don't want to find out where that limit lays.
If we deprecate methods because they can lead to easy mistakes or unexpected panics that seems okay to do. Even users that are annoyed by the deprecation warnings can see it is at least done for a good reason.
Doing deprecations because we consider a new name to be nicer is going to be a much harder sell.

Also duplicating 13 methods is not going to make our documentation any clearer.

The difficult part here is that I am arguing for not doing it on 0.4 while personally I don't mind it much if changes are smoothed out over time.

[pitdicker]

BTW I do kind of like the assume_ prefixes from time-rs because they IMO more clearly/explicitly convey the intended semantics. So maybe we should copy those instead of in_()?

I'd like to test both and see how it looks in some sample code.