Closed Aeledfyr closed 4 weeks ago
This may be changing in the near future. Mutating the environment is unsafe starting in the 2024 edition (due to be released in October), and I expect that the associated lint will be warn-by-default (if not force-warn) in all editions ≤2021 soon. If and when that happens, I will revisit the issue to see if it remains an issue.
Given the inherent lack of a stability promise and the fact that it may change relatively soon, I think it would be best to not document it at this time. My comment here remains my position.
As of time 0.3.36, any method that requires the system's local offset will fail on multithreaded unix-like systems, but this is not mentioned in the documentation for the
local-offset
feature, or any of the relevant methods.Places where this should hopefully be documented:
local-offset
featuretime::UtcOffset::local_offset_at
andtime::UtcOffset::current_local_offset
time::OffsetDateTime::now_local
297 gives a good description of this problem; it was closed after adding documentation in https://github.com/time-rs/time/commit/288c942a34e19fa38704bdde5e1d49fc21318be2.
However, this documentation was removed in https://github.com/time-rs/time/commit/b513927af2e2a48b87a5374510abf9e703422d36, and replaced with "Without [unsound_local_offset], any method that requires the local offset will return the
Err
variant." in the crate-level documentation.Later, https://github.com/time-rs/time/commit/110e17bb8461816551f7197a2aa2e34c981fa22d fully removed the reference to the local offset methods failing by default.
At this point, there is no documentation of the default behavior in places where people would look -- in the documentation of the
local-offset
feature or in the documentation of the methods that will fail, leading to a large number of issues asking about it: #591 #457 #297 #617 #538 #427 #645I'm open to making a PR to add documentation, but it'll likely need to be carefully phrased.