Graphql-dotnet: Fresh Release

[msheldon83]

Are there any plans to publish a new release of the library? There is at least one bug fix that I'm looking for that was fixed back in February.

[joemcbride]

There will not be any more 2.x releases, only 3.x. There have been several 3.x releases.

[andrewtyped]

I would like to understand better the release model for graphql-dotnet. I am not usually comfortable with adding pre-release dependencies to my production libraries, but this project goes through long phases of alpha dev (2.0 had ~1 year of alpha releases, 3.0 is at 7 months). It also seems alpha releases are no longer tagged or branched. What are the blockers preventing a stable release? I see a long tail of work under the 3.0 milestone, but also a long tail of open PR's not affiliated with any release. Do all these need closing before stability?

[joemcbride]

I would like to understand better the release model for graphql-dotnet.

There is no fixed release schedule.

I am not usually comfortable with adding pre-release dependencies to my production libraries

Many people do not have that same issue and 3.x has been in production for several people for quite some time.

What are the blockers preventing a stable release?

General documentation (both the text in the documentation itself, as well as the documentation site itself) and an upgrade guide. Because there are breaking changes, those should be documented.

I see a long tail of work under the 3.0 milestone, but also a long tail of open PR's not affiliated with any release. Do all these need closing before stability?

No, not all of these need closing. There are some more breaking changes that I would _prefer_ to get into 3.0, though those could be put off.

Since this is an OSS project, people work on what they want. That doesn't always align with what would be a targeted release. If the docs were ready, I would be just fine releasing 3.0 today.

[msheldon83]

I’d be happy to try to contribute to the docs or remaining enhancements. Can you point me to some issues that I can help resolve?

I missed the preview releases as that’s typically not my standard either but I’ll switch over as I’m not in prod yet and in anticipation of the stable release.

Thanks

Sent from my iPhone

On Oct 1, 2019, at 4:48 PM, Joe McBride [e-mail] wrote:

I would like to understand better the release model for graphql-dotnet.

There is no fixed release schedule.

I am not usually comfortable with adding pre-release dependencies to my production libraries

Many people do not have that same issue and 3.x has been in production for several people for quite some time.

What are the blockers preventing a stable release?

General documentation (both the text in the documentation itself, as well as the documentation site itself) and an upgrade guide. Because there are breaking changes, those should be documented.

I see a long tail of work under the 3.0 milestone, but also a long tail of open PR's not affiliated with any release. Do all these need closing before stability?

No, not all of these need closing. There are some more breaking changes that I would prefer to get into 3.0, though those could be put off.

Since this is an OSS project, people work on what they want. That doesn't always align with what would be a targeted release. If the docs were ready, I would be just fine releasing 3.0 today.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[sungam3r]

@msheldon83 https://github.com/graphql-dotnet/graphql-dotnet/milestone/4

@joemcbride Regarding documentation. I have already made changes to the documentation pages that are located on the site (docs2 folder). Do I understand correctly that this site still needs to be somehow manually updated? Now there is documentation for version 2.4.0. Wouldn't it be better to switch to the built-in wiki infrastructure of the github? I think that wiki will be much more convenient.

[joemcbride]

@msheldon83

I’d be happy to try to contribute to the docs or remaining enhancements. Can you point me to some issues that I can help resolve?

Here's the 3.0 milestones.

https://github.com/graphql-dotnet/graphql-dotnet/milestone/4

The major item I was looking to get in, as it is a breaking change, is #1140. #1143 should also be done. Those are probably the only major items that I think are critical, besides upgrade documentation. There's a few bugs and other enhancements but those can come later.

@sungam3r

Do I understand correctly that this site still needs to be somehow manually updated?

Yes. Last time I tried to deploy the documentation site it did not work. I believe the dependencies for the site need to be updated (it is using Gatsby) though I haven't investigated further.

Wouldn't it be better to switch to the built-in wiki infrastructure of the github? I think that wiki will be much more convenient.

It would maybe be more convenient for those writing the docs, though it wouldn't be as convenient for change tracking. I also think having the mini-site is a better documentation experience than the wiki. It would be nice to eventually have docs available for all major versions. Having the documents in source control helps with that. We can easily browse back to a specific version and pull those docs at that point in time.

[sungam3r]

As I understand wiki is also a git repository which one can clone and edit locally and then push changes - https://help.github.com/en/articles/viewing-a-wikis-history-of-changes

[sungam3r]

It would be nice to eventually have docs available for all major versions. Having the documents in source control helps with that. We can easily browse back to a specific version and pull those docs at that point in time.

So, wiki makes it easy.

[joemcbride]

No, you cannot easily swap between specific versions in the wiki - showing all of the docs for the specific version all at once. A wiki is not how I want to do the docs.

[sungam3r]

Ok. Suppose I’m writing a migration guide from 2.4.0 to 3.0.0. Should I make it a separate .md file in a directory with the rest .md documentation files? By the way, I am going to write it with an eye on the generated approved api files. Now we have a file for the current version (dev). I suggest adding a file for stable version 2.4.0 and the corresponding 2.4.0-3.0.0-dev-XXX diff file. After the release of version 3.0.0, we can repeat this cycle with next diff. The changes will be visual and it will be easy to compile a migration guide without forgetting anything. What do you think?

[hmvs]

@sungam3r Did you create a PR with the migration guide? If you create a branch I might help you with writing migration documentation.

[sungam3r]

We can say that I started work on this. Thanks for the help, but it's too early. There is nothing concrete yet. You can help by looking for some utility that automates the compilation of diff files like this. I first want to get a clear understanding of the changes, and only then add documentation.

[Shane32]

@joemcbride I see you are looking to get #1140 in before 3.0 drops, as it is a breaking change. If IValidationRule.Validate now becomes ValidateAsync, perhaps this would also be a good time to change IFieldResolver.Resolve to ResolveAsync. I have posted a pull request #1380 that describes and demonstrates these changes.

[ahaeber]

With regards to the documentation site. I would recommend switching over to Antora. Antora is a multi-repository documentation site generator based on Asciidoctor. It creates nice doc sites based on Asciidoctor (AFAIK a superset of Markdown, so current docs can be used as is). Antora supports using Git tags and branches as means to navigate between versions. For example by pointing to tag "v2.4.0" it shows docs for that version, and pointing to "master" branch it shows docs for the "latest" docs.

See https://gitlab.com/antora/antora.org/issues/20 for a list of public documentation sites that uses Antora, including Couchbase, Fedora, MuleSoft.

[shani117]

@joemcbride / @sungam3r - Any further update on the official 3.0 release? The release list on GitHub still shows 2.4 as the last release. I know there have been a lot preview releases on MyGet since then, but wanted to check on a official 3.0 release status. Can you please comment?

[sungam3r]

From my point of view, the situation has not changed. There is still no documentation to migrate to the new major version. Also there are some pending issues here https://github.com/graphql-dotnet/graphql-dotnet/milestone/4 . But it seems to me that the documentation is even more important than these issues. In any case, I rely entirely on the @joemcbride opinion in this matter.

[Shane32]

I have comprehensive upgrade documentation ready in draft form. It relies on PR #1511 being pulled (relating to data loaders). As @sungam3r is unfamiliar with data loaders, he cannot review it. @joemcbride has indicated he is looking forward to reviewing it, but has not done so yet.

I would also like to see some better error handling (such as contained within #1656 and #1658 ) make it into the 3.0 release as well, if possible.

Once PR #1511 is pulled, or at least reviewed, I will publish the draft upgrade documentation as a PR.

[sungam3r]

This month I hope to find time for a review. Lately busy.

[ghostknight63]

@Shane32 could you please have the draft published even before PR is merged?
It might help.

We're experiencing issues with 2.4.0 implementation leaking memory (very similar to https://github.com/graphql-dotnet/graphql-dotnet/issues/559), so we need to upgrade . Since there is no hope in stable version release any time soon, we need to accept the risk of using beta software, so any documentation will help, even if it's not 100% correct.

Thanks in advance!

[sungam3r]

@Shane32 It makes sense. I am still busy to review many PRs, sorry.

[Shane32]

@ghostknight63 Yes I'm working on it. Was hoping to get it done this last weekend but it didn't happen. Hopefully I can work on it this week. It should encompass a number of features that are still in draft form here. Are you using any other nuget packages that depend on the base graphql nuget package?

[Shane32]

@ghostknight63 Sorry I misunderstood you. I'm going to publish a beta branch, including several critical features that are not yet merged here. It will include upgrade documentation. It doesn't make sense to publish a draft of the upgrade docs here since it would not match the current beta.

[ghostknight63]

@Shane32 thanks a lot!
No, We're not using any vital dependent packages, only our own codes & utilities on top of.
Looks like I was able to fix build of my project at least after some guessing, however upgrade docs still would help for me to be more sure, that I did everything correctly. Thanks again!

[Mithras]

I really don't understand how people use GraphQL without DataLoader. Without https://github.com/graphql-dotnet/graphql-dotnet/pull/1511 whole graphql dotnet seems useless to me.

[Shane32]

I will have #1511 included as part of the beta nuget package.

[BenjaBobs]

I really don't understand how people use GraphQL without DataLoader. Without #1511 whole graphql dotnet seems useless to me.

We have our resolvers translate the GraphQL queries to Gremlin and use the graph database of Azure Cosmos DB, so in our case it's a bit like we're doing a massive "join" but without the enormous performance costs.
It definitely seems necessary for when resolving against a SQL database though.

[Shane32]

Heads up: We plan to release 3.0rc1 at the end of this month, including the new data loaders (#1511) and upgrade documentation. The final 3.0 release will be published shortly thereafter. Among many other improvements since 2.4.0, some of the newest features of 3.0 include better error handling and support for scoped services. Any assistance testing the release candidate will be appreciated - thanks!!

[sungam3r]

To be honest, I can't even count how many new features and bugfixes have appeared since version 2.4.0.

[Shane32]

@ghostknight63 Draft upgrade documentation is available in PR #1798

[Shane32]

3.0 was released on 9/2/2020. The latest release, 3.1.1, was released today. We are aiming for a minor release every month or two, depending on the number of fixes and improvements, with a major release every 6-12 months.