Path to Releases

[justjosias]

We need to think about releases now. Currently everyone just uses master and hopes nothing breaks. We try to ensure stability with every change, but sometimes things slip through.

My proposal:

• Release version 0.11.0, incrementing the current working version number (0.10.0)
• Generally adopt semantic versioning
• Distribute DLLs with releases
• Aim for stabilizing into 1.0 soon

This will help us meaningfully communicate API changes, allow bindings to clearly state which versions they support, possibly backport relevant fixes, and give us a place to distribute official DDL builds.

This is based on @dandeto's proposal in #700.

[lolgab]

Since the API is very small you could also distribute the library as a static library so people can statically link it in their programs.

[dandeto]

@justjosias We have made quite a bit of progress since version 0.10.0. Are there any additional milestones we need to hit before we create the v0.11.0 release?

@lolgab Really good idea. That can make it even easier to integrate into a preexisting build system. I know how to make a static lib on windows, but I will need to research it on Linux and MacOS a little more... though I think it is pretty simple.

[justjosias]

@dandeto The only blocking issue I see is figuring out the build system for Windows, since the behavior changed. What @abemedia mentioned about DLLs previously not being required to build has me concerned that this is too heavy a change. Can you elaborate? What do you think?

[dandeto]

@justjosias Thank you for pointing that out. I misunderstood the go build command a little bit, but after some experimentation I found that nothing has changed. DLLs actually were previously required to build. The only additional step I have created is running the build script or getting the DLLs from a release, which I think is better than updating and distributing them and the nuget package in our repo. I clarified this in the issue you linked.

[justjosias]

I think we are almost ready to make a release. We've done many fixes and improvements and changed enough behavior (particularly with webview_navigate) that it needs to be documented to provide users and binding maintainers with clarity.

Final changes to the build system should be made soon, including deciding how exactly to make the process easier for Go users and for those who want to use a static library.

[dandeto]

Since I have been working on the build script, I can make any improvements needed. What do you think should be changed for those use-cases?

[justjosias]

The main blocker for releasing v0.11.0 is fixing #728, #731, and maybe #730. I'm not familiar enough with the unbind function to fix them myself.

@dandeto When you have time, could you take another look at those?

[dandeto]

They're on my list! I've gotten very busy recently, but will get back to the code soon.

[SteffenL]

When was 0.10.0 released? I have seen version 0.10.0 mentioned before but no tag for it.

[justjosias]

@SteffenL There has been no official 0.10.0 release. I was using it to refer to the general state of the repo when we started working on it, since that's what I believe the previous maintainers called it. It's not clear, so I was just going to bump the version number and start from there.

[SteffenL]

@justjosias Oh, I see. In that case, is anything stopping us from using 0.10.0 as the next version instead 0.11.0?

[SteffenL]

I am positive to preparing for a release and focusing more resources on improving stability. Here are my immediate thoughts on the proposal. I realize that the following may be a bit too much so feel free to disregard irrelevant parts.

Release version 0.11.0, incrementing the current working version number (0.10.0)

Since 0.10.0 has never been officially released then to me it seems like we would be free to use 0.10.0 as the next version. It would be a nicer starting number but if that comes with complications then I do not mind using 0.11.0 too much.

Maybe we need to decide on a few things when it comes to releases:

• When when to bump the version number. We could either bump right after a release or right before a release. Both might have pros/cons.
• When and how to tag a release in the Git repository (annotation, signing).
• Whether to enforce signed tags, if possible.
• Restrictions on who is allowed to sign or push tags, if possible.
• Disallow pushing commits to master if not already disallowed.
• Restrictions for who is allowed to merge PRs.
• Whether we automate releases and to what degree we do so, and if/when someone has to "push the button" manually.

Anything else?

Generally adopt semantic versioning

Agreed. We need at least MAJOR.MINOR.PATCH. Do you have any thoughts on usage of prerelease labels, build metadata and what to embed in the source code and binaries?

Distribute DLLs with releases

It makes sense to distribute prebuilt binaries for Windows. Now that we support both MSVC and MinGW-w64 we will need to decide on a few things:

• Which compilers and versions to use.
• Whether to distribute binaries built with multiple compilers.
• Whether to distribute binaries with statically or dynamically linked C/C++ runtime libraries, or both.
• Whether to distribute one or both of debug/release builds of the library.
• Compile library with debug/release version of runtime libraries if applicable.
• What if any kind code signing to use or other ways to ensure data integrity of binaries (e.g. providing hashes).

Anything else?

Aim for stabilizing into 1.0 soon

I would like to see more thought going into API design before we think about a 1.0 release. In my opinion the current API makes it difficult to maintain high quality code, mainly due to questionable error handling and reporting, but also due to overlapping concerns that make features complicated to maintain and is prone to regressions.

This will help us meaningfully communicate API changes, allow bindings to clearly state which versions they support, possibly backport relevant fixes, and give us a place to distribute official DDL builds.

To help with any pending decisions, I have the following suggestions.

• API changes:
  • We should not break existing API but we can deprecate existing API, and we can add things to existing API in a backward-compatible way.
  • Deprecated API should have the same behavior as before the deprecation.
  • Deprecated API can be removed after a grace period or version. This can be documented in the API contract and get a changelog entry.
  • We can change behavior if users of the library wish to use new behavior while retaining backward-compatibility.
  • Changes should be documented in the API contract if we can provide backward-compatibility.
  • Changes also get a changelog entry.
• Bindings and version support:
  • The library must expose its own version. This lets users check if they support that version of the library.
  • The library can also check whether it is compatible with the user's headers.
• Backporting fixes:
  • I suggest not maintaining multiple versions of the library unless we can truly commit to doing so. If we build the library with backward-compatibility in mind then I do not think that we need to backport fixes. This keeps the release cycle simpler.
• Storage for binaries:
  • GitHub Releases is an option that comes to mind.

Remarks

PR #766 aims to solve many of the above points by embedding the library's version, introducing version checks, error codes, improved error handling and reporting, wider compatibility, etc. The foundation is there but it is considered to be a draft and I would appreciate more feedback so that we move in the right direction.

Given that we have not officially released anything since before the major library rewrite more than two years ago, it could make a lot of sense to consider including #766 in the first release after the library rewrite—after a feedback/improvement cycle of course.

[justjosias]

I don't see a problem with using 0.10.0. I was just wary of using something already informally referred if we changed the API significantly.

I can address some of the points related to security:

• Pushing to the master branch is disallowed
• Merging PRs is only allowed for a few, including @dandeto, @SteffenL, @nicklasfrahm, @justjosias, and a few previous maintainers. A review by other maintainers is not currently enforced.

Agreed. We need at least MAJOR.MINOR.PATCH. Do you have any thoughts on usage of prerelease labels, build metadata and what to embed in the source code and binaries?

I don't have any thoughts on those at the moment. MAJOR.MINOR.PATCH is the minimum goal I'm looking towards.

I would like to see more thought going into API design before we think about a 1.0 release. In my opinion the current API makes it difficult to maintain high quality code, mainly due to questionable error handling and reporting, but also due to overlapping concerns that make features complicated to maintain and is prone to regressions.

If we can maintain backwards compatibility with minor releases for a while, I think waiting before considering 1.0 is acceptable.

To help with any pending decisions, I have the following suggestions.

All of those suggestions are reasonable. We need to make a first release for future releases to reference. We should avoid breaking API compatibility with existing master, since it has been used for builds for over a year now. Backports won't be necessary as long as we maintain this.

[taozuhong]

Could publish webview as a MINGW package for MSYS2?

[SteffenL]

Could publish webview as a MINGW package for MSYS2?

It is a cool idea but to do it properly I imagine that the WebView2 SDK and maybe runtime would have to be available as packages as well. Just my immediate thought.