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.
简而言之:破坏 GraphQL schema 兼容性的变更会推进主版本号(major);插件接口的破坏性变更通常也会推进主版本号,但在极少数情况下可能随次版本(minor)更新发布;TypeScript 类型调整可能出现在修订版本(patch)中,但我们会尽最大努力将破坏性影响降到最低。此外,我们仅支持处于 LTS(长期支持)周期内的 Node 和 Postgres 版本——一旦某个版本结束 LTS,我们将不再提供支持。
Semver语义化版本(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.
PostGraphile 核心包(不含第三方插件)遵循语义化版本规范(semver):major.minor.patch。小型问题修复归入修订版本(patch),实用新特性归入次版本(minor),而破坏性变更则会发布为主版本(major)。
Stable schema保持 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.
PostGraphile 致力于帮助你构建易于维护的 GraphQL API。因此,任何会破坏现有 GraphQL schema 的改动(例如将原本非空的字段改为可空,或移除已有字段)都被视为破坏性变更,必须通过主版本更新发布(例如 5.0.0 -> 6.0.0)。为了在不破坏兼容性的前提下持续演进,我们通常会在新功能设为默认行为之前,先提供配置选项或更新后的 preset 供你主动启用。
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.
当我们引入新功能时,新增元素的名称有可能与你自己在 schema 中定义的内容发生冲突(因为它们共享同一个命名空间)。遇到这种情况时,系统会抛出错误,你可以通过禁用新功能(例如使用 disablePlugins、调整 behavior 等方式),或对其中一方乃至双方进行重命名来解决。这条例外规则是必要的——否则,每次向 GraphQL schema 添加哪怕一个新字段,都不得不升级主版本号。
Exception: schema ordering例外情况:schema 成员顺序
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.
我们并不认为 GraphQL schema 中字段、类型、枚举值、指令等成员排列顺序的变化属于语义差异,因此这类顺序变动可能会出现在修订版本(patch)中。通常我们不会轻易改动顺序(毕竟每次变动都要同步更新测试),但确实存在这种可能。
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):
如果你的项目要求 schema 成员严格保持特定顺序,可以通过插件来强制排序。例如,下面这个插件会按字母顺序对对象类型的字段进行排序(不过这通常并不是个好主意):
// 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!
相较于内置 preset 生成的 GraphQL schema,插件系统更具“实验性”。有时为了支持新特性或修复缺陷,我们不得不对某个插件或插件接口做微小的破坏性调整;如果评估下来这类变更影响的用户不到 1%,我们可能会将其包含在次版本更新中(例如 5.0.0 -> 5.1.0)。话虽如此,插件接口的破坏性变更依然是我们会竭力避免的严肃问题。凡是在官网文档中正式公开的接口,若非出于非常充分的理由,我们绝不会轻易破坏兼容性——因此请务必只依赖文档中明确记载的 API!
Exception: TypeScript types例外情况:TypeScript 类型
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.
TypeScript 本身在不断演进,我们的类型定义也有持续改进的空间。由于 PostGraphile 规模庞大,每次为了提升类型精确度就发布一个主版本显然不切实际,因此我们将 TypeScript 类型变更排除在语义化版本约束之外。我们会尽力避免造成大范围的类型报错;万一你在升级 PostGraphile 时确实遇到了 TypeScript 问题,请查阅对应版本的 Release Notes 获取修复方案或变通方法。
Exception: unmaintained Node.js and PostgreSQL例外情况:停止维护的 Node.js 与 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.
一旦某个 Node 或 PostgreSQL 的 LTS 版本不再受其官方维护团队支持,我们可能会在修订版本(不过更常见的是在次版本)中移除对该版本的支持。你或许觉得这违背了语义化版本规范,但我们并不这么认为(况且即便算违背,我们也会照做不误)。继续兼容已停止官方维护的 Node 或 PostgreSQL 版本毫无意义——由于这些版本可能存在未修复的安全漏洞,任何负责任的生产环境都不应继续使用;既然本就不该再使用它们,停止对其支持自然也不应算作破坏性变更。
Use a lockfile务必使用 lockfile
TL;DR: use a lockfile.
简而言之:请使用 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).
随着时间推移,PostGraphile 会放宽对 graphql 及其他依赖项的支持版本范围,并且不会为此专门推进主版本或次版本号。我们不把这类依赖范围扩展视为破坏性变更,因为我们默认你遵循 Node.js 最佳实践,在项目中使用了包锁文件,例如 Yarn 的 yarn.lock 或 npm 的 package-lock.json。此外,你还可以借助 Yarn 的 "resolutions" 功能等机制,将特定依赖(如 graphql)固定在指定版本(如 0.13.x)。