What started as a little hobby project has become an industry standard.

We want to express our sincere thanks to the GraphQL Java community, the 250+ code contributors and countless more who created issues and participated in discussions. Thanks to all volunteers who helped make GraphQL Java better!

Now we’d like to share fun stories about the last 10 years.

How we came to the library​

Andi's story​

I was working at a small company which used a REST(ish) API for their web app. This API evolved and had a lot of typical features added on top of rest like field selection, sub selections etc. to make it performant and practical useable. When a colleague pointed me to the imminent release of a new protocol called “GraphQL” by Facebook I was immediately convinced of its value because: it solved the API problems we had on a fundamental level.

I sat down for a week or so and invested all my free time to come up with the first version of GraphQL Java as quick as possible. Very quickly after I released a version 0.1 I already got a first contributor and user. (The) REST is history 🙂

Brad's story​

I was an architect at Atlassian on the Jira Service Desk product (now JSM) and we were embracing dynamic UIs driven by having more data called via browser calls. If you don't know what jQuery and AJAX is - just trust me, it was cool in its time.

We invented a REST endpoint nicked named The Smoosher - you made a call and we just smooshed all the data you need to paint the JSD portal screens. It worked but it clearly broke all the RESTian orthodoxy around resources and state and other networking dogma.

I started looking into GraphQL as a more architectural technique for getting the data you need for a dynamic UI. As we had a JVM back end, I started to look into graphql-java.

My first PR was adding the Instrumentation classes that kinda still exist today (albeit in a more efficient form). graphql-java became an after-work hobby to keep my hand in at coding (architects are always drawn away from coding towards the dark side called a rich text editor and eventually Keynote / Powerpoint)

Donna's story​

I started a new job on the same team as Andi and Brad. At the time, GraphQL was completely new to me, yet I knew I had to learn pretty quickly for the job! I like to learn by coding, so I picked a few bug tickets to give me a goal to aim for. Andi and Brad patiently explained concepts and reviewed my PRs (and still do!), making the whole experience much less daunting.

Contributing to GraphQL Java was easily the best decision I’ve made in my career. I was hooked from my first PR, kept contributing, and things snowballed from there. Soon I became a maintainer, and a dream came true when Andi and I published a book together, GraphQL with Java and Spring.

Cheers to many more years of GraphQL Java 🍻 Later this year we’ll be speaking at GraphQL Conference 2025, see you there!

This release is an unexpected breaking change release. It was made to help propagate a fix in the DataLoader library.

We consider v23.x poisoned and we don't recommend you use it because of the latent bug explained in the release notes on GitHub.

Going forward we will not be supporting v23.x, instead please skip this series and use v24.x going forward.

We are pleased to announce the release of graphql-java v23.0! Thanks to everyone in the community who contributed to the release, whether that was code, helping to report issues, or participating in discussions.

This is a breaking change release. Included are performance improvements and features.

For the full details, please see the release notes on GitHub.

See the CVE.org press release: https://www.cve.org/Media/News/item/news/2024/12/03/GraphQL-Java-Added-as-CNA

As side effect of this maturity it became clear over the least years, that performance is a key aspect that users are interested in. Especially in larger scale applications performance can have a huge impact on operational costs and user experience.

In GraphQL Java we leverage JMH aka Java Microbenchmark Harness to measure and compare different performance aspects.

Historically, performance testing was done manually by running JMH benchmarks on a local machine.

This comes with the obvious flaw that it's not reproducible over time and across different machines. A benchmark run on one developer's machine is not comparable to a run on another developer's machine (or often even the same machine months later).

We are very happy to share that we have now an automated performance testing setup in place to overcome these limitations by running the benchmarks in an isolated cloud environment.

Currently, it runs on every commit to the master branch and the results are stored in the
performance results folder. You can visualize and compare results with the JMH Visualizer tool, a free tool which runs in the browser. Our goal is to provide clear and reproducible performance improvements over time while preventing any regressions.

This work is sponsored and made possible by Atlassian and we are very grateful for their support.

This is a breaking change release, which includes major performance improvements. This release also introduces the @defer directive, which enables data to be received incrementally, rather than waiting until all data is resolved. This can reduce an application's time-to-interactive. See more on the @defer draft specification on the GraphQL Working Group's GitHub repo.

For the full details, please see the release notes on GitHub.

And a very Happy 8th Birthday to graphql-java, who celebrated their birthday last week!

This is a breaking change release, including upgrading to Java 11 and changes to parseValue coercion. See the full release notes on GitHub.

General release schedule​

Going forward, we plan to have 3 releases every year. We will alternate between releases containing breaking changes, and releases containing features and bugfixes (without breaking changes).

For example: our next release 20.1 will be in late March 2023, and this will be a feature and bugfix release without breaking changes. Therefore, we’re going to retain Java 8 in the 20.1 release. Our subsequent release will be around early July 2023 and will contain breaking changes, including upgrading to Java 11.

Security backports​

We will backport critical bugfixes and security fixes for versions dating back 18 months. These fixes will be backported depending on severity and demand. As security fixes are time sensitive, we will release them on demand instead of waiting for the next release date.

Bugfix backports​

We will backport important bug fixes at most 12 months. These fixes will be backported depending on the severity of the bug and demand.

Deprecations​

When code is deprecated, we will wait at least 12 months before removing it.

Version numbering​

We will continue to use major.minor version numbering.

A minor version can include bug fixes and features, but not breaking changes. A major version can include breaking changes.

Allowing for policy changes​

The aim of this release policy to give the community a better indication of release dates, what is contained in releases, and when fixes will be backported. However, we may make a pragmatic decision to diverge from this policy when required. For example, a major and urgent breaking change could result in two breaking change releases in a row. If we diverge from this release policy, we’ll make it clear in the release notes.

With Java 8 being released over 8 years ago and Java 17 more than one year ago, we think now is the right time to upgrade the minimum Java version GraphQL Java is developed against.

This means starting with version 21 you need to use at least Java 11 to run GraphQL Java.

Depending on the feedback we get, we plan to release bugfix releases for version 20 for some time, but no longer than until end of 2023.

Please discuss and leave feedback here

Special thanks to each of the 200+ contributors over the years, who have made this milestone possible.

We've added support for record-like property fetching, added performance improvements for PropertyDataFetcher and reduced object allocation.

Version 20 also introduces internationalization (i18n) for validation, parsing, and scalar coercion error messages. We have added German translations, and we would love to see more languages. If you would like to contribute, please open a pull request.

See the full release notes on GitHub.

Use Spring Initializr to create a GraphQL application. For a quick tutorial, please see our Spring for GraphQL tutorial.

See also the Spring for GraphQL documentation and the repo on GitHub.

Before the official Spring for GraphQL integration was released, there were many other GraphQL integrations for Spring, including the similarly named GraphQL Java Spring project from the GraphQL Java team, published under the com.graphql-java and com.graphql-java-kickstart group IDs. Many tutorials are still referring to this unrelated project.

Please use the official integration named "Spring for GraphQL", published under org.springframework and related group IDs.

At the same time we wanted to give an update regarding our LTS (Long Term Support) policy. Previously we maintained a LTS version of 9.x and after quite some time we announced 14.x as the next LTS.

The reality is that we didn't maintain 14.x really as a LTS version (we only released one bugfix release). This was mainly caused by the minimal community feedback and our limited time and resources.

Going forward we decided to no offer any LTS versions anymore. We will only actively maintain and bugfix the latest version (currently 17). We may backport critical bugfixes, but we are not committed to it.

If this is a huge problem for you or your Company and you are willing to help us with maintaining a LTS version you can reach us via email at hello at graphql-java dot com.

The bigger question behind this is: what is the information you want get out of this question? Why do you ask this question?

The thing is: spec releases are not really important and people misinterpret what they mean.

The GraphQL spec has five releases so far:

• two in 2015 (including the first published version)
• two in 2016
• one in 2018

As you can see in the first two years spec releases where quite frequently, but after the one in 2018, there has not been a release.

2017 was also the year the GraphQL Working Group was established. This group is the main forum to evolve the spec since then. Over time this group established a very high bar for every PR to be merged into the spec. (See the Contributing guidelines)

With this high standard set, nearly all implementations (including GraphQL Java) started to implement every merged PR instead of waiting for a big release. Because they are very confident this change will be released in this form, it is safe to implement it right away.

This treatment of merged PRs as de-factor releases is now an established rule in the GraphQL community. This explains why the whole GraphQL ecosystem has evolved a lot since 2018, even without a release.

A release is not needed anymore if every merged PR is like a mini release.

Future releases are more like an opportunity to look back and promote the work since the last release.

I personally hope that we make this de-facto rule, that evey PR is a mini release, more official. We should not use the word "draft" any more, but every merged PR should automatically result in a new GraphQL spec version which is formally approved by the GraphQL TSC.

Coming back to the question: "Which spec version of GraphQL is supported"? I hope by now it is clear why this question is probably not really helpful.

It is better to think about certain features you want to discuss instead referring to the spec releases.

Feedback or questions

We use GitHub Discussions for general feedback and questions.

Additionally to being strictly unopinionated regarding Threads, GraphQL Java is also fully reactive, implemented via CompletableFuture (CF). These two constrain together mean we rely on the CF returned by the user. Specifically we piggyback on the CF returned by the DataFetcher (or other async methods which can be implemented by the user, but we focus here on DataFetcher as it is by far the most important).

// Pseudo code in GraphQL Java

CompletableFuture<Object> dataFetcherResult = invokeDataFetcher();
dataFetcherResult.thenApply(result -> {
    // in which Thread  where this code happens is controlled by the CF returned
    continueExecutingQuery(result);
});

Blocking DataFetcher

Lets assume you are accessing a DB in a blocking way in your DataFetcher:

String get(DataFetchingEnvironment env) {
    return getValueFromDb(env); // blocking the Thread until the value is read from DB
};

This is not completely wrong, but not recommend in general as the consequence of this kind of DataFecher is that GraphQL can't execute the query in the most efficient way.

For example for the following query:

{
  dbData1
  dbData2
  dbData3
}

If the DataFetcher for these dbData fields don't return a CF, but block the Thread until the data is read, GraphQL Java will not work with maximum efficiency.

GraphQL Java can invoke the DataFetcher for all three fields in parallel. But if your DataFetcher for dbData1 is blocking, GraphQL Java will also be blocked and only invoke the next DataFetcher once dbData<n> is finished. The recommend solution to this problem is offloading your blocking code onto a separate Thread pool as shown here:

CompletableFuture<String> get(DataFetchingEnvironment env) {
    return CompletableFuture.supplyAsync( getValueFromDb(env), dbThreadPool );
};

This code will maximize the performance and will cause all three fields to be fetched in parallel.

Different pools for different work

The subsequent work done by GraphQL Java will be executed in the same dbThreadPool until it encounters a new DataFetcher returned by the user code and this new CF dedicates the Thread for the subsequent work.

If you want to have separate pools for different kind of work, one for the actual DataFetcher which normally involve IO and one of the actual GraphQL Java work (which is pure CPU), you need to switch back from your offloaded pool to a dedicated GraphQL Java pool before returning the CF. You can achieve this with code like this:

CompletableFuture<String> get(DataFetchingEnvironment env) {
    return CompletableFuture.supplyAsync( getValueFromDb(env), dbThreadPool )
        .handleAsync((result,exception) -> {
            if(exception !=null) throw exception;
            return result;
        }, graphqlJavaPool);
};

Notice the .handleAsync which doesn't do anything except forwarding the result, but on a different pool (graphqlJavaPool).

This way you have different pools for different kind of work (one for CPU bound GraphQL Java work and one for multiple ones for IO bound work), which can be configured and monitored independently.

In a fully reactive system

If your system is fully reactive your DataFetcher will more look like this

CompletableFuture<String> get(DataFetchingEnvironment env) {
    return callAnotherServiceNonBlocking(env); // returns CompletableFuture
};

The code above could be implemented via Async Http Client or WebFlux WebClient. Both provide fully reactive HTTP clients.

Because the code is non blocking there is no need to offload anything on a dedicated Thread pool to avoid blocking GraphQL Java.

You still might want to consider using a dedicated GraphQL Java pool as you otherwise would use Threads which are dedicated to IO. How much this is really relevant depends highly on your use case.

For example Async Http Client (AHC) uses by default 2 * #cores (this value comes actually from Netty) Threads. If you don't use a dedicated Thread Pool for GraphQL Java you might encounter situations under load where all AHC Threads are either busy or blocked by GraphQL Java code and as a result your system is not as performant as it could be. Normally only load tests in production like environments can show the relevance of different Thread pools.

Feedback or questions

We use GitHub Discussions for general feedback and questions.

The scenario

But first lets set the scene. Imagine we have a system that can return issues and the comments on those issues

{
  issues {
    key
    summary
    comments {
        text
    }
  }
}

Nominally we would have a graphql.schema.DataFetcher on issues that returns a list of issues and one on the field comments that returns the list of comments for each issue source object.

As you can see this naively creates an N+1 problem where we need to fetch data multiple times, one for each issue object in isolation.

We could attack this using the org.dataloader.DataLoader pattern but there is another way which will discuss in this article.

Look ahead via DataFetchingFieldSelectionSet

The data fetcher behind the issues field is able to look ahead and see what sub fields are being asked for. In this case it knows that comments are being asked for and hence it could prefetch them at the same time.

graphql.schema.DataFetchingEnvironment#getSelectionSet (aka graphql.schema.DataFetchingFieldSelectionSet) can be used by data fetcher code to get the selection set of fields for a given parent field.

DataFetcher issueDataFetcher = environment -> {
    DataFetchingFieldSelectionSet selectionSet = environment.getSelectionSet();
    if (selectionSet.contains("comments")) {
        List<IssueAndCommentsDTO> data = getAllIssuesWithComments(environment, selectionSet.getFields());
        return data;
    } else {
        List<IssueDTO> issues = getAllIssuesWitNoComments(environment);
        return issues;
    }
};

Imagine this is backed by an SQL system we might be able to use this field look ahead to produce the following SQL

SELECT Issues.Key, Issues.Summary, Comments.Text
FROM Issues
INNER JOIN Comments ON Issues.CommentID=Comments.ID;

So we have looked ahead and returned different data depending on the field sub selection. We have made our system more efficient by using look ahead to fetch data just the 1 time and not N+1 times.

Code Challenges

The challenge with this code design is that the shapes of the returned data is now field sub selection specific. We needed a IssueAndCommentsDTO for one sub selection path and a simpler IssueDTO for another path.

With enough paths this becomes problematic as it adds new DTO classes per path and makes out child data fetchers more complex

Also the standard graphql pattern is that the returned object becomes the source ie. graphql.schema.DataFetchingEnvironment#getSource of the next child data fetcher. But we might have pre fetched data that is needed 2 levels deep and this is challenging to do since each data fetcher would need to capture and copy that data down to the layers below via new TDOs classes per level.

Passing Data and Local Context

GraphQL Java offers a capability that helps with this pattern. GraphQL Java goes beyond what the reference graphql-js system gives you where the object you returned is automatically the source of the next child fetcher and that's all it can be.

In GraphQL Java you can use well known graphql.execution.DataFetcherResult to return three sets of values

• data - which will be used as the source on the next set of sub fields
• errors - allowing you to return data as well as errors
• localContext - which allows you to pass down field specific context

When the engine sees the graphql.execution.DataFetcherResult object, it automatically unpacks it and handles it three classes of data in specific ways.

In our example case we will be use data and localContext to communicate between fields easily.

DataFetcher issueDataFetcher = environment -> {
    DataFetchingFieldSelectionSet selectionSet = environment.getSelectionSet();
    if (selectionSet.contains("comments")) {
        List<IssueAndCommentsDTO> data = getAllIssuesWithComments(environment, selectionSet.getFields());

        List<IssueDTO> issues = data.stream().map(dto -> dto.getIssue()).collect(toList());

        Map<IssueDTO, List<CommentDTO>> preFetchedComments = mkMapOfComments(data);

        return DataFetcherResult.newResult()
                .data(issues)
                .localContext(preFetchedComments)
                .build();
    } else {
        List<IssueDTO> issues = getAllIssuesWitNoComments(environment);
        return DataFetcherResult.newResult()
                .data(issues)
                .build();
    }
};

If you look now you will see that our data fetcher returns a DataFetcherResult object that contains data for the child data fetchers which is the list of issueDTO objects as per usual. It will be their source object when they run.

It also passes down field specific localContext which is the pre-fetched comment data.

Unlike the global context object, local context objects are passed down from a specific field to its children and are not shared across to peer fields. This means a parent field has a "back channel" to talk to the child fields without having to "pollute" the DTO source objects with that information and it is "local" in the sense that it given only to this field and its children and not any other field in the query.

Now lets look at the comments data fetcher and how it consumes this back channel of data

DataFetcher commentsDataFetcher = environment -> {
    IssueDTO issueDTO = environment.getSource();
    Map<IssueDTO, List<CommentDTO>> preFetchedComments = environment.getLocalContext();
    List<CommentDTO> commentDTOS = preFetchedComments.get(issueDTO);
    return DataFetcherResult.newResult()
            .data(commentDTOS)
            .localContext(preFetchedComments)
            .build();
};

Notice how it got the issueDTO as its source object as expected but it also got a local context object which is our pre-fetched comments. It can choose to pass on new local context OR if it passes nothing then the previous value will bubble down to the next lot of child fields. So you can think of localContext as being inherited unless a fields data fetcher explicitly overrides it.

Our data fetcher is a bit more complex because of the data pre-fetching but 'localContext' allows us a nice back channel to pass data without modifying our DTO objects that are being used in more simple data fetchers.

Passing back Errors or Data or Both

For completeness we will show you that you can also pass down errors or data or local context or all of them at once.

It is perfectly valid to fetch data in graphql and to ALSO send back errors. Its not common but its valid. Some data is better than no data.

GraphQLError error = mkSpecialError("Its Tuesday");

return DataFetcherResult.newResult()
        .data(commentDTOS)
        .error(error)
        .build();

Merged Fields

First thing we are looking at is "merged fields".

GraphQL allows for a field to be declared multiple times in a query as long as it can be merged.

Valid GraphQL queries are:

{
  foo
  foo
}

{
  foo(id: "123")
  foo(id: "123")
  foo(id: "123")
}

{
  foo(id: "123") {
    id
  }
  foo(id: "123") {
    name
  }
  foo(id: "123") {
    id
    name
  }
}

Each of these queries will result in a result with just one "foo" key, not two or three.

Invalid Queries are:

{
  foo
  foo(id: "123")
}

{
  foo(id: "123")
  foo(id: "456", id2: "123")
}

{
  foo(id: "123")
  foo: foo2
}

The reason why they are not valid, is because the fields are different: in the first two examples the arguments differ and the third query actually has two different fields under the same key.

Motivation

The examples so far don't seem really useful, but it all makes sense when you add fragments:

{
  ...myFragment1
  ...myFragment2
}

fragment myFragment1 on Query {
  foo(id: "123") {
    name
  }
}
fragment myFragment2 on Query {
  foo(id: "123") {
    url
  }
}

Fragments are designed to be written by different parties (for example different components in a UI) which should not know anything about each other. Requiring that every field can only be declared once would make this objective unfeasible.

But by allowing fields merging, as long as the fields are the same, allows fragments to be authored in an independent way from each other.

Rules when fields can be merged

The specific details when fields can be merged are written down in Field Selection Merging in the spec.

The rules are what you would expect in general and they basically say that fields must be the same. The following examples are taken from the spec and they are all valid:

fragment mergeIdenticalFields on Dog {
  name
  name
}
fragment mergeIdenticalAliasesAndFields on Dog {
  otherName: name
  otherName: name
}
fragment mergeIdenticalFieldsWithIdenticalArgs on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: SIT)
}
fragment mergeIdenticalFieldsWithIdenticalValues on Dog {
  doesKnowCommand(dogCommand: $dogCommand)
  doesKnowCommand(dogCommand: $dogCommand)
}

The most complex case happens when you have fields in fragments on different types:

fragment safeDifferingFields on Pet {
  ... on Dog {
    volume: barkVolume
  }
  ... on Cat {
    volume: meowVolume
  }
}

This is normally invalid because volume is an alias for two different fields barkVolume and meowVolume but because only one of the some are actually resolved and they both return a value of the same type (we assume here that barkVolume and meowVolume are both of the same type) it is valid.

fragment safeDifferingArgs on Pet {
  ... on Dog {
    doesKnowCommand(dogCommand: SIT)
  }
  ... on Cat {
    doesKnowCommand(catCommand: JUMP)
  }
}

This is again a valid case because even if the first doesKnowCommand has a different argument than the second doesKnowCommand only one of them is actually resolved.

In the next example someValue has different types (we assume that nickname is a String and meowVolume is a Int) and therefore the query is not valid:

fragment conflictingDifferingResponses on Pet {
  ... on Dog {
    someValue: nickname
  }
  ... on Cat {
    someValue: meowVolume
  }
}

Sub selections and directives

One thing to keep in my mind is that the sub selections of fields are merged together. For example here foo is resolved once and than id and name is resolved.

{
  foo(id: "123") {
    id
  }
  foo(id: "123") {
    name
  }
}

This query is the same as:

{
  foo(id: "123") {
    id
    name
  }
}

The second thing to keep in mind is that different directives can be on each field:

{
  foo(id: "123") @myDirective {
    id
  }
  foo(id: "123") @myOtherDirective {
    name
  }
}

So if you want to know all directives for the current field you are resolving you actually need to look at all of the merged fields from the query.

Merged fields in graphql-js and GraphQL Java

In graphql-js merged fields are relevant when you implement a resolver and you need access to the specific ast field of the query. The info objects has a property fieldNodes which gives you access to all ast fields which are merged together.

In GraphQL Java depending on the version you are running you have List<Field> getFields() in the DataFetcherEnvironment or for GraphQL Java newer than 12.0 you have also MergedField getMergedField() which is the recommend way to access all merged fields.

We are happy to release the first version of the GraphQL Java Spring (Boot) project.

As described before this project complements the GraphQL Java core project if you build a fully operational GraphQL server with Spring.

Currently it supports GET and POST requests and allows for some basic customization.

In future we are looking into supporting more advanced features like file upload or subscriptions.

As always contributions are more than welcome and we are hoping to grow this project together with the community: please open a new issue or leave a comment on spectrum chat about your wishes.

More details on how to use it can be found on the github page: https://github.com/graphql-java/graphql-java-spring

This is not defined by the graphql specification per se so we are reluctant to add it to the core library and then have it turn up later as an officially specified type.

But it really is a badly needed type in your GraphQL arsenal and hence graphql-java-extended-scalars was born

https://github.com/graphql-java/graphql-java-extended-scalars

This will be a place where we can add non standard but useful extensions to GraphQL Java.

The major scalars we have added on day one are

• The aforementioned DateTime scalar as well as a Date and Time scalar
• A Object scalar or sometimes know as a JSON scalar that allows a map of values to be returned as a scalar value
• Some numeric scalars that constrain the values allowed such as PositiveInt
• A Regex scalar that allows a string to fit a regular expression
• A Url scalar that produces java.net.URL objects at runtime
• And finally an aliasing technique that allows you to create more meaningfully named scalar values

We hope you find them useful.

Cheers,

Brad

We think it is important to make it clear, that this is not the case: GraphQL Java aims to be a library used directly without any additionally abstraction on top. It was always build with this goal in mind.

To be fair: we didn't do a very good job so far to make that clear. For example up until recently we hosted several other projects which provided abstractions on top of GraphQL Java. This was because of historical reasons and we didn't give any guidance on when to use what. There are also currently more tutorials out there which don't use GraphQL Java directly compared to tutorials which do.

The other reason people might think that GraphQL Java is not suitable is because the core project doesn't provide any easy way to get a full service with HTTP endpoint up and running. And the existing third party projects providing for example Spring Boot support are adding abstractions.

The core project doesn't deal with any form of HTTP or JSON specific things and has on purpose basically no dependencies at all. This will not change, but we recognize the need for having an easy way to get a full service up and running. This is why we are currently working on first class Spring (Boot) support.

This is not done yet, but it will provide an easy way to integrate GraphQL Java in a Spring (Boot) application without adding any abstraction on top of GraphQL Java. It will also be extended over time with more advanced features like Apollo Defer support.

To recap:

1. GraphQL Java aims to be a first class library used directly
2. The GraphQL Java core project doesn't deal with HTTP/JSON and will continue not do it
3. The GraphQL Java Spring project will complement the core project in providing comprehensive Spring (Boot) support

Cheers,

Andi

We do that because we are optimizing for long-term growth: GraphQL Java is 3 1/2 years old and it is just getting started. This means more people will be positively affected from a better experience compared to the ones who need to refactor.

We do it also because of resource constraints: we are an open source private run project with limited time and resources. We can’t afford maintaining a badly designed project in the long-term. Every bad design, every bad naming makes adding features and adopting to new requirements harder, more time consuming and more unlikely. We also want to make external contributions as easy as possible because we can’t do it all ourself.

The last reason is personal and it is about fun. I don’t wanna maintain a badly designed project. I need to have fun if I wanna continue to invest a large amount of private time in GraphQL Java.

Does that mean we just refactor as crazy and break everything all the time? No it doesn’t. We follow some rules about breaking changes:

• We never take a functionality away. We deprecate things and make it clear that we don’t really support them anymore, but we don’t take them away without a clear alternative.

• We try to favor simple breaking changes the compiler will catch. For example renaming a method is such a simple change.

• We try to document in our release notes every breaking change clearly.

• Even if we prioritize clean design higher than API stability in general we always weigh the benefits of the change vs the cost of adapting to it. There is no hard rule to that, but we always ask: is it worth it?

But we understand that not every Organization allows for regular updating major versions of GraphQL Java. This is why we started to maintain a Long-term support (LTS) version of GraphQL Java: 9.x. We will continue to back port all bug fixes to 9.x for some time and we will announce when we will switch to a new LTS version.

It is not clear yet how long this time span will be and it depends also on your feedback. Please contribute to this spectrum thread and let us know what suits you best. If you have special needs and you don’t wanna discuss it in public you can also reach us via contact form.

Cheers,

Andi