URL Proposal

[leebyron]

Here's my pitch for how the built URLs could work:

Urls follow a /namespace/scalar/version hierarchy:

• https://scalars.graphql.org/
  • Lists out all scalars plus a search box
• https://scalars.graphql.org/namespace/
  • Lists out all scalars within a namespace.
  • Namespaces are required to be github usernames or orgs so we can render a link that replaces "scalars.graphql.org" with "github.com" and takes you somewhere useful.
• https://scalars.graphql.org/namespace/scalar
  • Metadata about a scalar spec including usage numbers (if we can get those, cdn hits API?) and links to all published versions (similar to https://spec.graphql.org/ ?)
  • Note that the scalar name in a URL is non-normative. It does not affect the name of the scalar found in someone's schema.
• https://scalars.graphql.org/namespace/scalar/vA.B.C
  • Loads a specific version of a scalar spec. This URL is immutable
• https://scalars.graphql.org/namespace/scalar/vA
  • Loads latest version which matches vA.X.X (this could be a 302 redirect)
• https://scalars.graphql.org/namespace/scalar/vA.B
  • Loads latest version which matches vA.B.X (this could be a 302 redirect)

Examples:

• https://scalars.graphql.org/andimarek/datetime/v1.0.0
  • Andi's original datetime proposal
• https://scalars.graphql.org/graphql/url/v2
  • A future official URL scalar type, second version, which include any latest prose edits

Semver rules:

• Major (vA.X.X)
  • Any change which is not backwards compatible with previous scalar specs
  • Example: a serialization format has changed
• Minor (vX.B.X)
  • Any behavioral change which is backwards compatible
  • Example: an input validation rule was made more lenient
• Patch (vX.X.C)
  • Non-behavioral changes
  • Example: Copy edits or additional examples

Implementation:

• Current version is added to the top of the scalar spec markdown file as front-matter
• This is always in the form vA.B to avoid merge conflicts for every PR.
  • The webpage generator should pick the next highest digit to create a vA.B.C from any previous built page if the frontmatter version does not change in a merged PR.
• Part of our template guidelines should include semver guidelines. PRs that include behavioral changes should be encouraged to update the version front-matter as part of their patch.

Example:

---
Name: DateTime
Version: v1.2
Authors: andimarek 
---

# DateTime

...

[leebyron]

Up for discussion @graphql/graphql-scalars

[andimarek]

Looks great @leebyron.

I am not sure the full semver range serves us well: Maybe just two numbers (major and minor) is enough for us to start with?

The finer semantics of "backward compatible" are not always really clear: I found it much easier to just differentiate between: you should pay attention to it (major change) and you don't need to care (minor).

[eapache]

I agree with Andi's point about versioning, and might even take it a step further - if the spec change is clearly not backwards compatible, is it even the same spec at that point? Should the new spec and the old spec really be sharing usage stats? I think that for most of the metadata/stats we might want for a spec, we'd really want them per major version, not shared across multiple major versions, in which case it might be simpler to follow the golang style and just say that a new major version should just be a new spec. This would still leave a single integer version for use for editorial changes.

The obvious con here is that we might end up with https://scalars.graphql.org/andimarek/datetime-v2/1. It's a bit gross, but not actually sure if it's a huge problem?

[andimarek]

I created a first implementation for this Url system: #3

[andimarek]

Coming back to this after more than two year: I strongly propose to keep it as simple as possible to get started.

I created a new PR #9 with a basic setup, which I intend to merge soon and iterate on it. We will probably go with a very manual URL schema like:

spec.graphql.org/<author-name>/<scalar-name>

This would be immutable and can't be changed after merged. We will probably allow editorial changes.

A new version of the scalar would need to be have a new scalar name, which might be <scalar-name>2, <scalar-name>3 etc.

In general we will very likely rely on manual reviews to get started. If that doesn't scale we might revisit the approach.

[dondonz]

Closing this issue as we're going ahead with immutable specifications, although we will permit non-semantic edits such as typos. See #13.

We're proceeding with @andimarek's simpler naming proposal.