Update documentation to prepare for release v3

[henriquemoody]

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 97.12%. Comparing base (2b36476) to head (ca4e2fa).

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1552      +/-   ##
============================================
+ Coverage     96.65%   97.12%   +0.47%     
  Complexity     1022     1022              
============================================
  Files           206      206              
  Lines          2569     2436     -133     
============================================
- Hits           2483     2366     -117     
+ Misses           86       70      -16     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[henriquemoody]

I was just playing with SpecKit, but I didn't do a good job with it. I just created the pull request to keep it here, see what I could salvage from it. Definitely too much stuff going on here!

[alganet]

@henriquemoody cool. Need any help with v3? I don't want to step in your toes, so I thought I'd better ask.

[henriquemoody]

There are absolutely no toes to step on! I'd be thrilled to see you back on Validation.

I'm on vacation until the 15th of December, and I don't have my laptop on me, but the most important thing I would like to get done is #1532. Basically, I want to track paths instead of IDs, because that will allow us to have a better error message. Right now when validating nested arrays, we can't really know what failed from a single message -- tracking paths will allow us to do that. I also wanted to use an object "Path" to do that, because it's easier to handle it, and we can have a specific formatter to handle that object, allowing us to have a distinction from when the {{name}} is actually a name or a path.

I haven't gotten that to work. First of all, from my playing around with it, I cannot make it an incremental change, so I gave up on not making a big bang. Secondly, I couldn't make it work in all cases, because the paths have gaps between them and building that correctly is very difficult.

If you want to play around with it I would be very happy, but honestly, just do whatever you're interested on doing, really. I just really want to get 3.0 released, and again no toes to step on -- besides, this library carries more your name than mine anyways!

[alganet]

@henriquemoody I can see the tests are passing, but I have some doubts about the intent of the change and what you are trying to achieve.

I left some comments in the PR!

If I understand this correctly, this change is indeed big, and it will take me some time to understand how the current architecture works before I make any meaningful progress. This problem is hard.

In the past, I remember using SplObjectStorage to leverage the fact that it can have objects as keys (in contrast to standard PHP arrays). In my mind, having an object (such as Path or something like it) as the key for the messages, would allow us to do things like ->path or ->id to it, or choose a default serialization when exporting to plain ->toArray(). That approach comes with its own drawbacks though (can't use PHP functions like array_map on SplObjectStorage).