Skip to main content
Version: Next

Versioning Policy

TL;DR: breaking changes to the GraphQL schema require a major version update. Breaking changes to the plugin interface would typically require a major version update, but in extremely rare cases may be included in a minor version update. TypeScript type changes may occur in patch updates, but we'll do our best to keep breakage to an absolute minimum. We only support LTS versions of Node and Postgres, once they are no longer LTS we no longer support them.

Semver​

PostGraphile (without third party plugins) follows semver: major.minor.patch. Small fixes go into a patch, nice new features go into a minor release, and breaking changes would require a major release.

Stable schema​

PostGraphile wants to help you make maintainable GraphQL APIs, as such any change that will break your existing GraphQL schema (e.g. by making something nullable that wasn't previously, or removing a field) would be a breaking change and require a major version update (e.g. 5.0.0 -> 6.0.0). To work around this, we will often add configuration options (or updated presets) to opt into new functionality before it is enabled by default.

Exception: naming clashes​

It's possible that when we add new functionality, the name of it will clash with something that you've added to your schema (since it shares the same namespace). If this happens, an error will be raised and you should address it by either disabling the new functionality (via disablePlugins or behaviors or similar) or by renaming one or both entities. This exception is required, otherwise we could never add another field to the GraphQL schema without a major version bump.

Exception: schema ordering​

We do not see changes in the order of fields, types, enum values, directives, etc in a GraphQL schema as a semantic difference, and thus may change them in a patch release. Generally we won't, because when we do we have to update our tests, but it might happen.

If you require schema entities to be in a particular order, you can enforce an order via a plugin, for example this plugin sorts object type fields alphabetically (which is probably not a good idea):

// Make sure this is the last plugin to be added, and if necessary add
// `after: [...]` to it containing a list of the names of all the plugins that
// add fields.
const SortFieldsAlphabetically: GraphileConfig.Plugin = {
  name: "SortFieldsAlphabetically",
  version: "0.0.0",

  schema: {
    hooks: {
      GraphQLObjectType_fields(fields) {
        const entries = Object.entries(fields);
        entries.sort(([a], [z]) => a.localeCompare(z, "en-US"));
        return Object.fromEntries(entries);
      },
    },
  },
};

Exception: plugins​

Plugins are seen as more "experimental" than the GraphQL schema generated by the built in presets. Sometimes we need to make tiny breaking changes to a plugin or the plugin interface in order to enable some new functionality or fix some bug, if we deem that these are likely to affect less than 1% of users then we might include them in a minor release (e.g. 5.0.0 -> 5.1.0). Despite this, breaking changes to the plugin interface are seen as a major issue and will be avoided as much as possible. Interfaces that are documented on the website(s) will not be broken without a very good reason - so stick to the documented APIs!

Exception: TypeScript types​

TypeScript is constantly changing, and our types can always be improved. Since PostGraphile is such a large project it wouldn't make sense to release a major version every time we make a TypeScript type more accurate, and thus we exclude TypeScript from semver. We will do our best to avoid major issues, and in the unlikely event that you hit TypeScript issues when upgrading PostGraphile be sure to check the release notes for fixes or workarounds.

Exception: unmaintained Node.js and PostgreSQL​

Once an LTS version of Node or PostgreSQL is no longer supported by its maintainers, we may drop support for it in a patch release (although it's more likely that we'd use a minor release). You may feel that this is a violation of semver, but we do not (and also, even if it is, we're going to do it anyway). Supporting unsupported versions of Node or PostgreSQL does not make sense, no reasonable user should be using these unsupported versions because they may contain unpatched security vulnerabilities, and since no-one should be using them, dropping support for them should not be a breaking change.

Use a lockfile​

TL;DR: use a lockfile.

PostGraphile will add support for wider versions of GraphQL (and other dependencies) over time without requiring a major or minor update. PostGraphile does not treat these as breaking changes as it's assumed that you follow Node.js best practices and use a package lockfile, such as yarn.lock (yarn) or package-lock.json (npm). You can use features such as yarn's "resolutions" to pin a particular dependency (such as graphql) to a particular version (such as 0.13.x).