cc @jamillambert

cc @Kixunil (no mention in PR description because of our merge script.)

Last time we did this there was push back by Kixunil because he did not like updating the API files

I also pushed back on this last time and I am still not a fan. For one, anything with 12k line diff makes you asking isn't there a better way.

s/makes you asking/makes me ask

In e8606d67fb3d3c8bda4b3d68f6488644e1e199d0:

Trailing whitespace in contrib/api.sh

Otherwise I think this is a great idea.

@yancyribbens yes, there is an initial 12k diff. In future the diffs should be much smaller and only green.

yes, there is an initial 12k diff

Yes, I understand that. It will also cause much larger commits every time by embedding this metadata for every commit, even though one could get this information by comparing the results of this script between two commits.

Otherwise I think this is a great idea.

I thought this was taken out last time with good reason. I mean, I appreciate the Github warning message when the API is being changed, even though it gets annoying when it creates the warning for every new commit.

will also cause much larger commits every time by embedding this metadata for every commit

git will absolutely compress the contents of multiple commits if it is the same.

I mean, I appreciate the Github warning message when the API is being changed,

I don't care about the Github message. I want to have a git history of the API changes. It was taken out last time because Kix complained about it and he gets a veto on stuff here (though in this case I was strongly tempted to override that veto..) when he's present.

In any case, I think you'll find it much less annoying when it's applied only to crates that are near-stable and intended not to change.

I want to have a git history of the API changes.

This could be created from a script that goes through the commit history and compares the api of two commits and then puts the result someplace.

It was taken out last time because Kix complained about it and he gets a veto on stuff here (though in this case I was strongly tempted to override that veto..) when he's present.

I think it was added though during the last time Kix disappeared. If he comes back again, is it going to get a veto again and then taken out again. Probably not, but I thought he made compelling arguments last time which I agree with.

In any case, I think you'll find it much less annoying when it's applied only to crates that are near-stable and intended not to change.

I guess that's part of working in a community is living with the decisions of others even when you don't agree. Anyway, it might annoy me but I'll live.

My main concern is that this adds an extra step to the contribution process. If every single PR requires us to update them due to a minor version upgrade in a dependency, it could become quite frustrating and potentially discourage contributions.

This depends on how often we expect these to change, which also depends on our dependancies. I am okay to try it again and revert if this gets annoying.

If every single PR requires us to update them due to a minor version upgrade in a dependency, it could become quite frustrating and potentially discourage contributions.

This isn't about dependencies, but about our own API. And this won't affect every PR -- only the ones that change the API. Which for near-stable crates, we do want to discourage.

And since we have currently have no path towards 2.0, with @Kixunil even claiming that there won't be one, preventing changes to the API is almost a must.

I pulled all the CI and docs stuff out of #2713

Now includes idea from #2893

Also can you pull the actual construction of the API files into their own commit? It can be the first commit (so initially there is nothing enforcing them) if that makes things nicer for you. But they overwhelm the diff and are hard to filter out (I think you need something like git show -- ^api/ api/README.md or something).