Add CONTRIBUTING, CHANGELOG and minimal documentation

umbraco-community · Nov 6, 2019 · 781b447 · 781b447
1 parent 762a8c1
commit 781b447
Show file tree

Hide file tree

Showing 4 changed files with 145 additions and 39 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Change log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## 0.1.0 - 2018-10-12
+
+-   First release
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,33 @@
+# Contributing
+
+## Bug Reports & Feature Requests
+
+Please use the [issue tracker](https://github.com/rasmusjp/umbraco-graphql/issues) to report any bugs or file feature requests.
+
+## Developing
+
+### Prerequisites
+
+-   Visual Studio
+-   IIS Express
+
+### Setup
+
+First build the Solution
+
+Run the `samples/Website` project, this will start IIS Express listeninng on `http://localhost:49937`
+
+Install Umbraco with the starter kit, so you have some sample data.
+
+### Folder structure
+
+```
+.
+├── samples                            # Sample projects
+│   └── Website                        # Sample/development site
+├── src                                # Source Files
+│   └── Our.Umbraco.GraphQL            # Main Project
+├── test                               # Tests Projects
+│   └── Our.Umbraco.GraphQL.Tests      # Unit Tests
+└── tools                              # Build tools
+```
diff --git a/README.md b/README.md
@@ -10,17 +10,15 @@ Please note this **should not be used in production**, since there are **no secu
 
 ## How does it work
 
-An Owin middleware exposes Umbraco Published Content as a GraphQL endpoint.
-
-GraphQL types are dynamically generated for all Umbraco document types (content and media), with all the properties as fields. They all implement an interface `PublishedContent` which implements the generic Umbraco properties as fields.
+GraphQL types are dynamically generated for all Umbraco document types (content and media), with all the properties as fields.
 
 ## Installation
 
 The preferred way to install GraphQL for Umbraco is through NuGet
 
 ### Option 1: NuGet
 
-GraphQL for Umbraco is available as a NuGet [package](https://www.nuget.org/packages/Our.Umbraco.GraphQL).
+GraphQL for Umbraco is available as a [NuGet package](https://www.nuget.org/packages/Our.Umbraco.GraphQL).
 
 To install run the following command in the [Package Manager Console](https://docs.nuget.org/docs/start-here/using-the-package-manager-console)
 
@@ -32,40 +30,40 @@ PM> Install-Package Our.Umbraco.GraphQL
 
 Clone the repository and run the Website (F5 in Visual Studio), install Umbraco with the starter kit and start exploring the API using the GraphQL Playground by opening `/umbraco/graphql`.
 
-### Urls
-
-| Method | Url              | Description        |
-| ------ | ---------------- | ------------------ |
-| GET    | /umbraco/graphql | GraphQL Playground |
-| POST   | /umbraco/graphql | GraphQL endpoint   |
-
-### Querying
-
-The Umbraco queries/types can be found under the `umbraco` field.
-
-```graphql
-{
-    umbraco {
-        content {
-            atRoot {
-                all {
-                    ...
-                }
-                ...
-            }
-            byId(id: "id") {
-            }
-            byType {
-                ...
-            }
-            byUrl(url: "url") {
-                ...
-            }
-        }
-    }
-}
-```
+## Docs
+
+The docs can be found [here](docs/index.md)
+
+## TODO
+
+-   [x] GraphQL Playground
+-   [x] Schema Stitching (extending types)
+-   [x] Metrics
+-   [x] Published Content
+-   [ ] Published Media
+-   [ ] Dictionary
+-   [ ] Statistics (field usage etc.)
+-   [ ] Deprecation (Content Types and Properties)
+-   [ ] API Tokens (OAUTH) with permissions (for content types and properties)
+-   [ ] Data Types
+-   [ ] Document Types
+-   [ ] Media Types
+-   [ ] Member Types
+-   [ ] Content
+-   [ ] Media
+-   [ ] Members
+-   [ ] Documentation
+
+## Contributing
+
+Anyone can help make this project better - check out our [Contributing guide](CONTRIBUTING.md)
+
+## Authors
+
+-   [Rasmus John Pedersen](https://www.github.com/rasmusjp)
+
+## License
 
-### Extending the Schema with your own types
+Copyright © 2018 Rasmus John Pedersen
 
-Take a look at the [Star Wars sample](samples/Website/Starwars).
+GraphQL for Umbraco is released under the [MIT License](LICENSE)
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,67 @@
+# Documentation
+
+## Configuration
+
+When installing the [NuGet package](https://www.nuget.org/packages/Our.Umbraco.GraphQL) a new file `App_Start/GraphQLComponent.cs` is added to the project, it contains the bootstrapping code for adding GraphQL to the project and the default configuration
+
+```csharp
+var path = $"/{_globalSettings.GetUmbracoMvcArea()}/graphql";
+
+app.UseUmbracoGraphQL(path, _factory, opts =>
+{
+    opts.Debug = HostingEnvironment.IsDevelopmentEnvironment;
+    opts.EnableMetrics = true;
+    opts.EnableMiniProfiler = false;
+    opts.EnablePlayground = true;
+});
+```
+
+The configuration options are:
+
+| Option                           | Description                                                                                              |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| CorsPolicyProvider               | The Cors Policy Provider                                                                                 |
+| Debug                            | Should exceptions be exposed in the response                                                             |
+| EnableMetrics                    | Should metrics be enabled                                                                                |
+| EnableMiniProfiler               | Should MiniProfiler be enabled                                                                           |
+| EnablePlayground                 | Should the GraphQL Playground be enabled                                                                 |
+| PlaygroundSettings               | Custom settings for the [GraphQL Playground](https://github.com/prisma-labs/graphql-playground#settings) |
+| SetCorsPolicy(CorsPolicy policy) | Sets the Cors Policy                                                                                     |
+
+## Default Urls
+
+| Method | Url              | Description        |
+| ------ | ---------------- | ------------------ |
+| GET    | /umbraco/graphql | GraphQL Playground |
+| POST   | /umbraco/graphql | GraphQL endpoint   |
+
+## Querying
+
+The Umbraco queries/types can be found under the `umbraco` field.
+
+```graphql
+{
+    umbraco {
+        content {
+            atRoot {
+                all {
+                }
+                # ... document types are added as fields
+            }
+            byId(id: "id") {
+            }
+            byType {
+                # ... document types are added as fields
+            }
+            byUrl(url: "url") {
+            }
+        }
+    }
+}
+```
+
+## Metrics
+
+[Apollo Tracing](https://github.com/apollographql/apollo-tracing) is enabled by default and is displayed in the GraphQL Playground, it collects the execution time for each field.
+
+If you need more insight, [Miniprofiler](https://miniprofiler.com/dotnet/) can be enabled by setting the option `EnableMiniprofiler=true`, MiniProfiler is implemented throughout the Umbraco code base and collects a lot of metrics. The data will be accessiblo in the `extensions.miniProfiler` field in the response.