diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..c8bdc70 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,4 @@ +# Contributor Code of Conduct + +Please review the GraphQL Foundation Code of Conduct at +https://graphql.org/codeofconduct/. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ca912e7..a9456e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,73 @@ # GraphQL Custom Scalars Specification Contribution Guide -TODO +Thanks for contributing to GraphQL Scalars. + +The goal of the GraphQL Scalars project is to provide a directory of GraphQL +Custom Scalar specifications, contributed by the community. Contributed +specifications will be hosted on a GraphQL Foundation owned domain +https://scalars.graphql.org, which can be referenced with the built-in +`@specifiedBy` GraphQL directive. + +GraphQL Custom Scalar specifications are language agnostic and thus can be used +to document and standardize behavior across different languages. + +We will confirm the domain details soon. We are currently setting this up. + +Please ensure that you read the +[Code of Conduct](https://graphql.org/codeofconduct/) before contributing to +this project. + +## How to contribute + +1. Copy the `template-string.md` + [template](https://github.com/graphql/graphql-scalars/blob/main/scalars/template-string.md) + for Custom Scalars based on the built-in String Scalar, or otherwise use the + `template.md` + [template](https://github.com/graphql/graphql-scalars/blob/main/scalars/template.md) + for all other Custom Scalars. Templates are located in the + [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars). + +2. [Open a new pull request](https://github.com/graphql/graphql-scalars/pulls) + for each Custom Scalar specification you would like to add. + +3. Modify your selected template, and save it in the correct place + `scalars/contributed//.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. + +### Contributor License Agreement + +This repository is managed by EasyCLA. Project participants must sign the free +[GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) +before making a contribution. You only need to do this one time, and it can be +signed by +[individual contributors](http://individual-spec-membership.graphql.org/) or +their [employers](http://corporate-spec-membership.graphql.org/). + +To initiate the signature process please open a PR against this repo. The +EasyCLA bot will block the merge if we still need a membership agreement from +you. + +You can find +[detailed information here](https://github.com/graphql/graphql-wg/tree/main/membership). +If you have issues, please email +[operations@graphql.org](mailto:operations@graphql.org). + +## Review process + +Your specification pull request will be reviewed by a maintainer of the +[graphql-scalars repository](https://github.com/graphql/graphql-scalars). The +maintainers will verify that the template has been completed, but note that the +correctness of the specification is the responsibility of the original +contributor. + +## Immutable specifications + +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. + +A new version of a Custom Scalar specification should have a new scalar name, +such as `2`, `3`, or a completely different name like +OffsetDateTime is different to DateTime. diff --git a/scalars/contributed/andimarek/date-time.md b/scalars/contributed/andimarek/date-time.md index e64f61a..ea44e52 100644 --- a/scalars/contributed/andimarek/date-time.md +++ b/scalars/contributed/andimarek/date-time.md @@ -2,7 +2,7 @@ "Author: andimarek" -"Date: 18.10.2022" +"Date: 2022-10-18" This is a String based Scalars (TODO: add link to explanation). diff --git a/scalars/guide.md b/scalars/guide.md index ecd6c5d..908b8e5 100644 --- a/scalars/guide.md +++ b/scalars/guide.md @@ -166,30 +166,3 @@ values for logically identical values. For example a `MyLocalDate` scalar could accept the literals `"01-10-2022"` and `"01102022"` as input for the first of October 2022, but the result coercion should always return one of the possible representations. - -## Scalars specification outline - -A Scalars specification must clearly define the three observable aspects of a -Scalar: - -1. The possible JSON result values - -2. The possible literal input values - -3. The possible JSON variable input values - -Provide positive and negative examples for each of the values. - -The Scalar should also be given a name. - -### Example implementation outline - -- Background - -- Naming recommendation - -- Valid values - -- Examples - -- References diff --git a/scalars/new-scalar.md b/scalars/new-scalar.md index 5a1bf27..4a74256 100644 --- a/scalars/new-scalar.md +++ b/scalars/new-scalar.md @@ -1,6 +1,74 @@ -# Guide to contribute a new Scalar +# Custom Scalar specification contribution guide -In order to contribute a new Scalar, please open a new PR for each new Scalar. +Thanks for contributing to GraphQL Scalars. -Copy either "template.md" or "template-string.md" and modify it. The new file -should be under "scalars/contributed//.md" +The goal of the GraphQL Scalars project is to provide a directory of GraphQL +Custom Scalar specifications, contributed by the community. Contributed +specifications will be hosted on a GraphQL Foundation owned domain +https://scalars.graphql.org, which can be referenced with the built-in +`@specifiedBy` GraphQL directive. + +GraphQL Custom Scalar specifications are language agnostic and thus can be used +to document and standardize behavior across different languages. + +The scalars will be hosted at https://scalars.graphql.org. We are currently +setting this up. + +Please ensure that you read the +[Code of Conduct](https://graphql.org/codeofconduct/) before contributing to +this project. + +## How to contribute + +1. Copy the `template-string.md` + [template](https://github.com/graphql/graphql-scalars/blob/main/scalars/template-string.md) + for Custom Scalars based on the built-in String Scalar, or otherwise use the + `template.md` + [template](https://github.com/graphql/graphql-scalars/blob/main/scalars/template.md) + for all other Custom Scalars. Templates are located in the + [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars/tree/main/scalars). + +2. [Open a new pull request](https://github.com/graphql/graphql-scalars/pulls) + for each Custom Scalar specification you would like to add. + +3. Modify your selected template, and save it in the correct place + `scalars/contributed//.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. + +### Contributor License Agreement + +This repository is managed by EasyCLA. Project participants must sign the free +[GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) +before making a contribution. You only need to do this one time, and it can be +signed by +[individual contributors](http://individual-spec-membership.graphql.org/) or +their [employers](http://corporate-spec-membership.graphql.org/). + +To initiate the signature process please open a PR against this repo. The +EasyCLA bot will block the merge if we still need a membership agreement from +you. + +You can find +[detailed information here](https://github.com/graphql/graphql-wg/tree/main/membership). +If you have issues, please email +[operations@graphql.org](mailto:operations@graphql.org). + +## Review process + +Your specification pull request will be reviewed by a maintainer of the +[graphql-scalars repository](https://github.com/graphql/graphql-scalars). The +maintainers will verify that the template has been completed, but note that the +correctness of the specification is the responsibility of the original +contributor. + +## Immutable specifications + +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. + +A new version of a Custom Scalar specification should have a new scalar name, +such as `2`, `3`, or a completely different name like +OffsetDateTime is different to DateTime. diff --git a/scalars/template-string.md b/scalars/template-string.md index 0a17534..01534be 100644 --- a/scalars/template-string.md +++ b/scalars/template-string.md @@ -1,30 +1,33 @@ -# This template is meant to be copied and modified - -# This template is meant for Scalars which are based on the build in String Scalar +# This template is meant to be copied and modified. This template is meant for Scalars which are based on the built-in String Scalar # Custom Scalar spec \ "Author:\ " -"Date: \" +"Date: \" # Overview -Provide an overview what this Scalar does and which +Provide an overview of what this Scalar does and provide any background +information. # Name -Talk about the name and list alternatives, if available. +Provide a recommended Scalar name and list alternatives, if available. # Result spec Define which Strings can be returned. +Provide positive and negative examples of String return values. + # Input spec Define which String values are accepted as input as GraphQL Literal and as JSON raw input. +Provide positive and negative examples of literal and JSON raw input values. + # References List external references, other background information etc. diff --git a/scalars/template.md b/scalars/template.md index 93c2da5..0613589 100644 --- a/scalars/template.md +++ b/scalars/template.md @@ -4,29 +4,35 @@ "Author:\ " -"Date: \" +"Date: \" # Overview -Provide an overview what this Scalar does and provide any background +Provide an overview of what this Scalar does and provide any background information. # Name -Talk about the name and list alternatives, if available. +Provide a recommended Scalar name and list alternatives, if available. # Result JSON spec Define which JSON values can be returned. +Provide positive and negative examples of JSON values. + # Literal Input spec Define which GraphQL Literals are accepted as input. +Provide positive and negative examples of literals. + # Raw Input JSON spec Define which JSON values are accepted as input. +Provide positive and negative examples of JSON values. + # References List external references, other background information etc.