mirrors/jiff
1
0
Fork 0
mirror of https://github.com/BurntSushi/jiff.git synced 2025-12-23 08:47:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

doc: final touch-ups before 0.2.0

Browse source
This commit is contained in:
Andrew Gallant 2025-02-10 21:25:29 -05:00
parent c587fddbb7
commit 0ba2c63c85
No known key found for this signature in database
GPG key ID: B2E3A4923F8B0D44
6 changed files with 25 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

4
CHANGELOG.md
View file

@ -1,7 +1,7 @@
# CHANGELOG
0.2.0 (TBD)
===========
0.2.0 (2025-02-10)
==================
This is a new semver incompatible release of Jiff. It contains several breaking
changes. I expect most users of Jiff to be able to upgrade without any changes.
The fundamental API organization of Jiff has not changed.

6
COMPARE.md
View file

@ -42,7 +42,7 @@ should be able to run any of the programs in this section:
anyhow = "1.0.81"
chrono = "0.4.38"
chrono-tz = { version = "0.9.0", features = ["serde"] }
jiff = { version = "0.1.0", features = ["serde"] }
jiff = { version = "0.2.0", features = ["serde"] }
serde = "1.0.203"
serde_json = "1.0.117"
tzfile = "0.1.3"
@ -688,7 +688,7 @@ should be able to run any of the programs in this section:
```toml
anyhow = "1.0.81"
jiff = { version = "0.1.0", features = ["serde"] }
jiff = { version = "0.2.0", features = ["serde"] }
time = { version = "0.3.36", features = ["local-offset", "macros", "parsing"] }
```
@ -1034,7 +1034,7 @@ should be able to run any of the programs in this section:
```toml
anyhow = "1.0.81"
hifitime = "3.9.0"
jiff = { version = "0.1.0", features = ["serde"] }
jiff = { version = "0.2.0", features = ["serde"] }
```
### Time zone database integration

14
DESIGN.md
View file

@ -485,14 +485,11 @@ tracker][github-issue-leap].
## Why isn't there any integration with `std::time::Duration`?
The omission of `std::time::Duration` from the `jiff 0.1.0` release was quite
intentional. Firstly, a `Duration` is an absolute time, meaning there is no way
to distinguish between `3600 seconds` and `1 hour`. Secondly, a `Duration` is
unsigned, which makes some API interactions awkward.
It is likely that there will eventually be at least some integration points
with `std::time::Duration`. [This issue][github-issue-duration] discusses some
of the challenges.
The initial release of `jiff 0.1` originally left out any integration
points with `std::time::Duration`. Since then, `SignedDuration` has
been added to Jiff. And `TryFrom` trait implementations have been added
to both `SignedDuration` and `Span` to make conversions between it and
`std::time::Duration` easier.
## What are the `ZoneDifference` and `ZonedRound` types for?
@ -630,7 +627,6 @@ serious confusion and conflicts in names when someone wants to use both an
[POSIX TZ]: https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html
[IANA Time Zone Database]: https://en.wikipedia.org/wiki/Tz_database
[TAI]: https://en.wikipedia.org/wiki/International_Atomic_Time
[github-issue-duration]: https://github.com/BurntSushi/jiff/issues/21
[github-issue-leap]: https://github.com/BurntSushi/jiff/issues/7
[`java.time`]: https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html
[NodaTime]: https://nodatime.org/

18
README.md
View file

@ -87,8 +87,8 @@ Fourth, run it with `cargo run`:
```text
$ cargo run
Compiling jiff v0.1.0 (/home/andrew/rust/jiff)
Compiling jiff-play v0.1.0 (/home/andrew/tmp/scratch/rust/jiff-play)
Compiling jiff v0.2.0 (/home/andrew/rust/jiff)
Compiling jiff-play v0.2.0 (/home/andrew/tmp/scratch/rust/jiff-play)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.37s
Running `target/debug/jiff-play`
2024-07-10T19:54:20-04:00[America/New_York]
@ -108,10 +108,11 @@ documentation lists the full set of supported features.
### Future plans
My plan is to iterate on the Jiff API and make occasional breaking change
releases over the next ~year. Assuming API breaking changes have settled down
after about one year's time, my plan will be to release Jiff 1.0 and commit to
the API for a long period of time. (Measured, at least, in years.)
With `jiff 0.2` out about 6 months after the `jiff 0.1` initial release, my
plan remains roughly the same as it started. That is, I'd still like to get a
`jiff 1.0` release out this summer 2025 (in about 6 months) and then commit to
it indefinitely. This plan may change if something critically wrong is found
with the current API.
The purpose of this plan is to get Jiff to a 1.0 stable state as quickly as
possible. The reason is so that others feel comfortable relying on Jiff as
@ -124,6 +125,11 @@ that makes it hard to do the wrong thing. Second to that is performance. Jiff
should have reasonable performance, but there are likely areas in which it
could improve. See the `bench` directory for benchmarks.
Note that performance is still an important goal. Some aspects of Jiff have
had optimization attention paid to them, but many still have not. It is a goal
to improve where we can, but performance will generally come second to API
comprehension and correctness.
### Platform support
The question of platform support in the context of datetime libraries comes up

2
bench/Cargo.toml
View file

@ -21,7 +21,7 @@ path = "src/bench.rs"
[dependencies]
criterion = "0.5.1"
jiff = { version = "0.1.0", path = ".." }
jiff = { path = ".." }
chrono = "0.4.38"
chrono-tz = "0.9.0"

4
src/lib.rs
View file

@ -176,8 +176,8 @@ Fourth, run it with `cargo run`:
```text
$ cargo run
Compiling jiff v0.1.0 (/home/andrew/rust/jiff)
Compiling jiff-play v0.1.0 (/home/andrew/tmp/scratch/rust/jiff-play)
Compiling jiff v0.2.0 (/home/andrew/rust/jiff)
Compiling jiff-play v0.2.0 (/home/andrew/tmp/scratch/rust/jiff-play)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.37s
Running `target/debug/jiff-play`
2024-07-10T19:54:20-04:00[America/New_York]