Merge pull request graphql#13 from graphql/contribution-guidelines

dondonz · web-flow · commit be1476dc1cca · 2022-11-09T10:22:58.000+11:00
Add contribution guide and code of conduct
diff --git a/CODE_OF_CONDUCT.md 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
@@ -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/<github-user-name>/<scalar-name>.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 `<scalar-name>2`, `<scalar-name>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
@@ -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
@@ -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
@@ -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/<your-name>/<scalar-name>.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/<github-user-name>/<scalar-name>.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 `<scalar-name>2`, `<scalar-name>3`, or a completely different name like
+OffsetDateTime is different to DateTime.
diff --git 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 \<name\>
 
 "Author:\<github user name\> "
 
-"Date: \<the date of the first publication\>"
+"Date: \<the date of the first publication in YYYY-MM-DD format\>"
 
 # 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
@@ -4,29 +4,35 @@
 
 "Author:\<github user name\> "
 
-"Date: \<the date of the first publication\>"
+"Date: \<the date of the first publication in YYYY-MM-DD format\>"
 
 # 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.
