From 2bf134f2bb9b60c6c758de96f9580ab43075c4d9 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Tue, 23 Dec 2025 13:49:38 +0100 Subject: [PATCH 1/6] Add versioning and `graphql` namespace --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 46e3453..6e7cbbc 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ this project. [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars). 2. Modify your selected template, and save it in the correct place - `scalars/contributed//.md` in - the + `scalars/contributed//v/.md` + in the [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars/contributed). The directory location is important, as this will form part of the reference URL for your specification. In case you are using an organization name, we @@ -52,30 +52,58 @@ review process for new specifications under `contributed/` is very light. Anyone may review pull requests. Feedback may or may not be incorporated at the discretion of the original author. When they consider the pull request has -reached a satisfactory state, but not before a 2 week review window, the author +reached a satisfactory state, but not before a 2-week review window, the author may ask a TSC member to merge the pull request. The TSC will then merge the pull request without further discussion. ### Review process for other parts of this repository -This document, and all content excluding `contributed/` may be changed with the +This document and all content excluding `contributed/` may be changed with the [TSC](https://github.com/graphql/graphql-wg/blob/main/GraphQL-TSC.md)'s approval. This is usually longer than reviewing new specifications. -### Immutable specifications +## Versioning -Specification semantics must not change, as specifications are publicly -available reference documents. We will permit small edits which do not change -specification semantics, such as typo fixes. +Specifications in this repository are versioned with a major and minor version, +such as `2.0`: -A new version of a custom scalar specification must use a new URL but may still -recommend using the old name. +```graphql +scalar DateTime + @specifiedBy(url: "https://scalars.graphql.org/my_username/date-time/v2.0/") +``` -For example, `scalars/contributed/my_username/date-time-v2.md` may recommend -using `DateTime` for the scalar name. +Editorial changes, such as typos, that do not change the semantics of a +specification are allowed without changing the version. -You may use a `-v` suffix to indicate new versions, but this is not a -requirement. +Every other change MUST create a new version. + +Versions in the `0.x` range SHOULD be used to indicate a rapidly evolving +specification that should be used with care. + +For version `1.0` and later, the minor version MAY be bumped for smaller +changes. The major version SHOULD be bumped for bigger changes. What constitutes +a smaller or bigger change is left to the appreciation of the specification +author. + +New versions SHOULD use the same recommended name. + +[!NOTE] + +> Some scalars in this repository do not have a version for historical reasons. +> Moving forward, all scalars MUST have a version. + +## The `graphql` namespace + +The `graphql` namespace contains specifications that have been approved by the +GraphQL TSC. While not part of the official GraphQL specification, those scalars +specifications are deemed high quality and recommended to use liberally. + +Anyone may submit a specification for inclusion in the `graphql` namespace by +opening a pull request and adding the item to a primary GraphQL working group +agenda. + +The pull request is merged when it gets 5 TSC approvals and has addressed all +requests for changes, but no sooner than the following primary working group. ## Licensing From 68f1af4659d0e9b8a08f1b2bb5693c5eb0a86a4a Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 24 Dec 2025 19:50:30 +0100 Subject: [PATCH 2/6] Put version at the end --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e7cbbc..f55617d 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ this project. [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars). 2. Modify your selected template, and save it in the correct place - `scalars/contributed//v/.md` + `scalars/contributed///v/index.md` in the [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars/contributed). The directory location is important, as this will form part of the reference From 46f7f19c47d330fd96098b0f59b0ddf81f330029 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 24 Dec 2025 19:51:49 +0100 Subject: [PATCH 3/6] Better versioning --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f55617d..d704ab3 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ this project. [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars). 2. Modify your selected template, and save it in the correct place - `scalars/contributed///v/index.md` + `scalars/contributed///v.md` in the [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars/contributed). The directory location is important, as this will form part of the reference @@ -69,7 +69,7 @@ such as `2.0`: ```graphql scalar DateTime - @specifiedBy(url: "https://scalars.graphql.org/my_username/date-time/v2.0/") + @specifiedBy(url: "https://scalars.graphql.org/my_username/date-time/v2.0.md") ``` Editorial changes, such as typos, that do not change the semantics of a From bf3b91445911e4ec593fd42a01a936e99403c0dd Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 24 Dec 2025 19:53:40 +0100 Subject: [PATCH 4/6] Update README.md Co-authored-by: Glen --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d704ab3..83330a6 100644 --- a/README.md +++ b/README.md @@ -95,8 +95,8 @@ New versions SHOULD use the same recommended name. ## The `graphql` namespace The `graphql` namespace contains specifications that have been approved by the -GraphQL TSC. While not part of the official GraphQL specification, those scalars -specifications are deemed high quality and recommended to use liberally. +GraphQL TSC. While not part of the official GraphQL specification, these specifications +are regarded as authoritative and are recommended for interoperability. Anyone may submit a specification for inclusion in the `graphql` namespace by opening a pull request and adding the item to a primary GraphQL working group From a3d5f3ed9baca4a376130ffa87ff697d49fd23fd Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 25 Dec 2025 16:47:20 +0100 Subject: [PATCH 5/6] format --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 83330a6..3d9b797 100644 --- a/README.md +++ b/README.md @@ -95,8 +95,9 @@ New versions SHOULD use the same recommended name. ## The `graphql` namespace The `graphql` namespace contains specifications that have been approved by the -GraphQL TSC. While not part of the official GraphQL specification, these specifications -are regarded as authoritative and are recommended for interoperability. +GraphQL TSC. While not part of the official GraphQL specification, these +specifications are regarded as authoritative and are recommended for +interoperability. Anyone may submit a specification for inclusion in the `graphql` namespace by opening a pull request and adding the item to a primary GraphQL working group From b5c9ae218f70a8e6e31c48b38091ac1ba528a15a Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Tue, 30 Dec 2025 10:35:12 +0100 Subject: [PATCH 6/6] Remove `graphql` namespace --- README.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/README.md b/README.md index 3d9b797..4b730d3 100644 --- a/README.md +++ b/README.md @@ -92,20 +92,6 @@ New versions SHOULD use the same recommended name. > Some scalars in this repository do not have a version for historical reasons. > Moving forward, all scalars MUST have a version. -## The `graphql` namespace - -The `graphql` namespace contains specifications that have been approved by the -GraphQL TSC. While not part of the official GraphQL specification, these -specifications are regarded as authoritative and are recommended for -interoperability. - -Anyone may submit a specification for inclusion in the `graphql` namespace by -opening a pull request and adding the item to a primary GraphQL working group -agenda. - -The pull request is merged when it gets 5 TSC approvals and has addressed all -requests for changes, but no sooner than the following primary working group. - ## Licensing Specifications contributed to the GraphQL Scalars repository are part of the