Embedio: Provide a more complete release note

[bufferUnderrun]

Describe the bug

I am using EmbedIO on many projects and updating to each new release has become a nightware due to lack of informations.

I was using the v2.2.9 and upgrading v2.7.3, there are some breaking changes. Example :

Update WebApiController
C# public async Task<bool> PostJsonData() { // no longer works //var data = this.ParseJson<MyData>(); // replace by the new added HttpContext property var data = HttpContext.ParseJson<MyData>(); ... return true; }

So, i have to rewrite my controller.action and extension method.

Add Items to IHttpContext
Why this new property ?

Github version VS Nuget Version
The last github version is v2.7.2 whereas nuget version is v2.7.3. So what's the differences or commits ?

The main problem is i have to find, read, understand all commits to know what has changed between each release. And quite frankly, if i follow all the threads about v3, this new version is frightening me...

Expected behavior

To my mind, having a well explain README file for new users is a good start but having a complete release note for current user is very important.

I know it's taking time but some actions could be very usefull when releasing new version :

• list (and link to ?) commits that fix bug.
• list (and link to ?) commits that add features. Provide a small snippet to explain the gain (ie: the Items property added)
• provide a migration guide when breaking change (ie: this. replace by HttpContext. in WebApi)
• sync the github version with the nuget version. One way could be to add a digit to the nuget version (ie: github 2.7.2, nuget 2.7.2.1). So when the bug come from nuget package, just update the last digit (ie: 2.7.2.2).

Finally, very thanks to this great project !

[geoperez]

Hello @bufferUnderrun

I'm sorry for the inconvenience, we have been making too many changes and too little documentation. And we are going to fix this issue.

Regarding your questions.

1 - I would improve and sync the current release notes (but I don't like the idea to add them to the README file), and include sample code as you request.
2 - EmbedIO v3.0 will be a BREAKING CHANGE in many ways. But @rdeago has been documenting everything, so if you want to upgrade to this version you will find enough migration notes.

Thanks again for your support.

[bufferUnderrun]

@geoperez i agree, release note and readme are 2 separated files because 2 differents goals. I'll take time to dig deeper in the v3 and read migration notes.

Thanks for your answer

[rdeago]

@bufferUnderrun first of all I want to thank you. I mean, really! I've been scared away from enough open-source projects suffering from exactly the same issues, to know that too seldom someone takes the time to speak up about them in the interest of everyone.

Yes, we need release notes, as well as more attention to documentation as a whole.

Yes, we also need clearer commit messages.

Yes, we need to follow semantic versioning as if our lives depended on it.

It's absolutely no excuse that I've been a contributor for just a couple weeks. I know I've already made my share of mistakes, and I have very little to say in my defense.

That being said, we also both agree the EmbedIO remains a great project. @mariodivece and @geoperez have been doing a great job creating and maintaining it over the course of five years. Other people, including you, have contributed both bug fixes and enhancements, but the burden of maintenance and release (and an overwhelming majority of commits) is on @geoperez's shoulders alone.

Your post uncovered the tip of an iceberg IMHO. EmbedIO has become both too "big" to treat it as a side project, and too "small" for the rigid procedures found in some bigger projects. I think we need to find a balance: documentation is paramount, as well as consistent style, but bug fixes need to be released as quickly as possible, and new contributors don't have to be scared or annoyed by bureaucracy (quoting @geoperez, _"It's open source, it's got to be fun!"_)

So what does EmbedIO need to come of age, so to speak? I'd like to share my two cents:

1. Procedures - We need to standardize a lot of things: code style, commit messages, Git workflow, PRs, releases... We need to put all that standards down in writing and, to the maximum extent possible, employ tools to enforce them with minimum effort and without confusion.

2. Contributors - Advancing a project is not only a matter of coding. It would be great if someone took the time to review XML docs, for instance. Or write some more example code. Even commenting on issues helps. We are a small community, everything counts.

I'm reopening this issue, hoping to stimulate further discussion.

[geoperez]