Stable write logic

[tjoyal]

TLDR: Introduce .sort.to_h on write.

A common issue with using the deprecation toolkit in large organizations is that new faults are appended to the end of the file, which in a collaborative environment, can cause unnecessary merge conflicts.

By implementing .sort.to_h, we can ensure that deprecations are organized in a predictable manner. This reduces merge conflicts by aligning the order of the deprecations with the order of the original test file.

Additionally, I've revised the write method to prevent unnecessary file system creation, updates, and deletions where not required.

Lastly, I've incorporated logic to prevent file updates when the original and updated content are logically equivalent. In the context of an existing project, reordering the YAML content with .sort.to_h can be disruptive if there are no significant changes. I've chosen not to update the file in such cases, but an alternative approach could be to enforce the new ordering regardless.

I'm unsure of the best way to test this proposal, but existing tests do validate the overall functionality.

[etiennebarrie]

Yeah I've been bitten by this, the approach to avoid unnecessary changes sounds reasonable.

[Edouard-chin]

It's been a very long time I didn't have a look at this gem. But if I remember correctly, the deprecations where written in the same order they were triggered purposedly.
This was to ensure that the next time a test runs, the same order of deprecation would be triggered, this was to catch flaky tests.

I believe that if we want to order them, we'd need to order them when they get triggered otherwise we'd have false positive because of

deprecation_toolkit/lib/deprecation_toolkit/collector.rb

Line 33 in eb6e762

deprecations_without_stacktrace <=> other.deprecations_without_stacktrace

I'll check tomorrow when I have a bit of time between 2 onboarding sessions :)

[Edouard-chin]

Ah, I missed that the ordering is done on the test names not on the actual deprecations array.
All good, thank you !