Guard semantic versioning for major changes using binary compat checks in .fsproj #194

Activity

1. abelbraaksma commented on Apr 29, 2024

   

   abelbraaksma

   on Apr 29, 2024

   Last edited by abelbraaksma

   MemberAuthor

   More actions

   I see a similar thing happened with StartingContext, which disappeared in a point-release (13.2 -> 13.3). I'd assume that one could've easily been deprecated first with a message saying how to get rid of it... And same thing: breaking changes should really only happen in major releases ;).

   I'm maintaining someone else code here, which had:

   [<AutoOpen>]
   module FsHttpExtensions =
       let makeCustUrl suffix = $"{HttpConfig.BaseUrl}/customers/{DataSetup.KNOWN_CUSTOMER_GUID}/%s{suffix}"
       let makeBaseUrl suffix = $"{HttpConfig.BaseUrl}/%s{suffix}"
   
       type IRequestContext<'T> with
   
           /// Create a GET request from HttpConfig.BaseUrl
           [<CustomOperation("GET_BASE")>]
           member this.GetBase(context: IRequestContext<StartingContext>, suffix) = this.Get(context, makeBaseUrl suffix)
   
           /// Create a POST request from HttpConfig.BaseUrl
           [<CustomOperation("POST_BASE")>]
           member this.PostBase(context: IRequestContext<StartingContext>, suffix) = this.Post(context, makeBaseUrl suffix)
   

   Here I just replaced the StartingContext with _ for auto-generalization. It now defaults to HeaderContext. Not sure that is correct. I hope the code will still run.

   I can always just rollback and go with an older version, but I prefer not to.

   
2. SchlenkR commented on Apr 29, 2024

   

   SchlenkR

   on Apr 29, 2024

   Member

   More actions

   Thanks @abelbraaksma for the points, and time taken. I see no ranting. I appreciate that you shared your thoughts.

   To make a long story short: There's a gap to that has to be bridged; between what is realistic for me as maintainer, and the understandable and legitim points brought up here (and other points).

   • Marking things obsolete won't be possible for several reasons.
   • Breaking changes should definitely result in a major version, and must not be introduced in minor versions. That did happen; my honest apologies for the inconvenience. I will keep 2 eyes on it.
   • There is no migration log anymore. Instead, breaking changes (and all other changes) are going to be documented in the release notes located in build props, with some eventual hints on how to migrate (see here: https://fsprojects.github.io/FsHttp/Release_Notes.html)

   Regarding StartingContext: It disappeared for the sake of being able to specify template-like requests (using the CE notation), and then using the CE notation to define the verb later (see here: https://fsprojects.github.io/FsHttp/Composability.html) Before that change, StartingContext was used to constrain that the verb must come before any request headers or body. But there's this comment that I might be come up one day:

   FsHttp/src/FsHttp/Dsl.fs

   Lines 25 to 27 in 625184c

   	module internal HeaderContext =
   	// TODO: I really(!!) have to code the URL stuff on type level;
   	// this makes problems all over the place; feels like C# :D

   Apart from that, I (currently) don't see any big changes coming up, and I regard the library and it's API as "quire stable" :)

   Thank you, and again, I appreciate your thouhgs very much.
3. abelbraaksma commented on May 5, 2024

   

   abelbraaksma

   on May 5, 2024

   MemberAuthor

   More actions

   Hi @SchlenkR, thanks for the insights and pointers!

   About "keeping two eyes on it", quite recently, a new build task was added for .NET projects which allows you to check for binary incompatibilities of any .NET library against a baseline version in NuGet.

   • See: Use .NET Package Validation to check for binary compat against baseline dotnet/fsharp#12368
   • Which mentions https://devblogs.microsoft.com/dotnet/package-validation/
   • And specifically, this section: https://devblogs.microsoft.com/dotnet/package-validation/#validation-against-baseline-package-version

   From what I read there, it is a very small change to your fsproj files and it will, at the very least, throw an error if this happens accidentally.
4. abelbraaksma commented on May 5, 2024

   

   abelbraaksma

   on May 5, 2024

   MemberAuthor

   More actions

   PS: I believe this can be closed with no action, as apart from me documenting this behavior by reporting it, there's not really anything to change r.n. ;).
5. abelbraaksma

   closed this as completedon May 5, 2024
6. SchlenkR

   reopened this on May 9, 2024
7. SchlenkR

   changed the title [-]Undocumented backward incompatible parameter change in functions like `deserializeJsonWithTAsync` and `toJsonTAsync` etc[/-] [+]Guard semantic versioning for major changes using binary compat checks in .fsproj[/+] on May 9, 2024
8. SchlenkR commented on May 9, 2024

   

   SchlenkR

   on May 9, 2024

   Member

   More actions

   Reopening the issue with changed title.

   Thanks @abelbraaksma for the info. That seems to be worth having a look at and eventually implement it.

   About "keeping two eyes on it", quite recently, a new build task was added for .NET projects which allows you to check for binary incompatibilities of any .NET library against a baseline version in NuGet.
   ...
   From what I read there, it is a very small change to your fsproj files and it will, at the very least, throw an error if this happens accidentally.

   👍React with 👍1Reacted by Abel Braaksma
9. github-actions

   added

   enhancementNew feature or requestNew feature or request

   breaking change

   on Mar 10, 2026