chore: mode developer docs to a different page (#72)

openfga · Sep 28, 2023 · 73c8283 · 73c8283
1 parent 2f448cf
commit 73c8283
Show file tree

Hide file tree

Showing 3 changed files with 129 additions and 53 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,5 @@ node_modules
 client/server
 .vscode-test
 .vscode-test-web
-.DS_Store
+.DS_Store
+.idea/
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ VS Code extension that provides syntax highlighting for the [OpenFGA](https://op
 [![Open VSX Version](https://img.shields.io/open-vsx/v/OpenFGA/openfga-vscode)](https://open-vsx.org/extension/OpenFGA/openfga-vscode)
 [![Release](https://img.shields.io/github/v/release/openfga/vscode-ext?sort=semver&color=green)](https://github.com/openfga/vscode-ext/releases)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/openfga/vscode-ext/blob/main/LICENSE)
-[![Discord Server](https://img.shields.io/discord/759188666072825867?color=7289da&logo=discord "Discord Server")](https://discord.gg/8naAwJfWN6)
+[![Discord Community](https://img.shields.io/discord/759188666072825867?color=7289da&logo=discord "Discord Community")](https://discord.gg/8naAwJfWN6)
 [![Twitter](https://img.shields.io/twitter/follow/openfga?color=%23179CF0&logo=twitter&style=flat-square "@openfga on Twitter")](https://twitter.com/openfga)
 
 ## About
@@ -19,8 +19,8 @@ OpenFGA is designed to make it easy for application builders to model their perm
 
 - [OpenFGA Documentation](https://openfga.dev/docs)
 - [OpenFGA API Documentation](https://openfga.dev/api/service)
-- [Twitter](https://twitter.com/openfga)
-- [OpenFGA Discord Community](https://discord.gg/8naAwJfWN6)
+- [OpenFGA on Twitter](https://twitter.com/openfga)
+- [Discord Community](https://discord.gg/8naAwJfWN6)
 - [Zanzibar Academy](https://zanzibar.academy)
 - [Google's Zanzibar Paper (2019)](https://research.google/pubs/pub48190/)
 
@@ -36,7 +36,7 @@ You can install the OpenFGA VS Code plugin from:
 
 ## Usage
 
-The extension currently offers 3 core features, with more to come.
+The extension currently offers 4 core features, with more to come.
 
 - Syntax Highlighting for OpenFGA files
 - A unique theme for OpenFGA for VS Code
@@ -46,69 +46,93 @@ The extension currently offers 3 core features, with more to come.
 
 ![Prompt to set OpenFGA Dark color scheme](resources/set-color-scheme.png)
 
-- A command to transform `OpenFGA` files to `JSON`
-	- Open an `OpenFGA` file in the editor 
+- A command to transform `.fga` OpenFGA files to `JSON`
+	- Open a `.fga` OpenFGA file in the editor 
 	- Open the `Command Pallette` using Ctrl+Shift+P (Windows) or Command+Shift+P (OSX)
 	- Select `OpenFGA: Transform DSL to JSON`
 	- A new tab will open with the transformed code
 
 ![Prompt to execute OpenFGA: Transform DSL to JSON command](resources/transform-command-select.png)
 
-## Development
-
-- Run `npm install` in the root directory. This installs all necessary npm modules.
-- Run `npm run compile && npm run test-node` to execute the client node test suite.
-
-### Distribution (Optional)
-
-To generate an installable build of this extension, you can do the following:
-
-- Run `npm install --global @vscode/vsce` to get the latest version of `vsce` for packaging 
-- Run `vsce package` to generate an installable `VISX` artifact for testing or distribution
-
-### Structure
-
-```
-.
-├── client // Language Client
-│   ├── src
-│   │   ├── test // End to End tests for Language Client / Server
-│   │   ├── extension.node.ts // Language Client node entry point
-│   │   └── extension.browser.ts // Language CLient web entry point
-├── package.json // The extension manifest.
-└── server // Language Server
-    └── src
-        ├── server.node.ts // Language Server node entry point
-        ├── server.browser.ts // Language Server web entry point
-        └── server.common.ts // Language Server common code
+- Validation of OpenFGA's `.fga` files
+	- As you type in a `.fga` OpenFGA file in the editor, the extension will highlight errors that make your models invalid 
+
+## Workflow to use it with the FGA CLI
+
+The extension works great when combined with the [FGA CLI](https://github.com/openfga/cli) to iterate on your model and test it.
+
+In order to do that:
+1- Create a working directory to house the files for your store
+2- Inside this directory, create a `model.fga` file with your model
+3- Alongside the `model.fga`, create a `store.yaml` file with the following syntax
+
+```yaml
+---
+name: Store Name # store name, optional
+model_file: ./model.fga # a global model that would apply to all tests
+tuples: # global tuples that would apply to all tests, optional
+  - user: folder:1
+    relation: parent
+    object: folder:2
+  - user: user:anne
+    relation: editor
+    object: folder:1
+tests: # required
+  - name: test-1
+    description: testing that the model works # optional
+    tuples: # tuples that only apply within the scope of this test
+      - user: user:beth
+        relation: viewer
+        object: folder:2
+    check: # a set of checks to run
+      - user: user:anne
+        object: folder:1
+        assertions:
+          # a set of expected results for each relation
+          can_view: true
+          can_write: true
+          can_share: false
+      - user: user:beth
+        object: folder:2
+        assertions:
+          # a set of expected results for each relation
+          can_view: true
+          can_write: false
+          can_share: false
+    list_objects: # a set of list objects to run
+      - user: user:anne
+        type: folder
+        assertions:
+          # a set of expected results for each relation
+          can_view:
+            - folder:1
+            - folder:2
+          can_write:
+            - folder:1
+            - folder:2
+          can_share: []
+      - user: user:beth
+        type: folder
+        assertions:
+          # a set of expected results for each relation
+          can_view:
+            - folder:2
+          can_write: []
+          can_share: []
 ```
 
-### Running the Client
-
-- Run `npm install` in the root directory. This installs all necessary npm modules.
-- Open the root directory in VS Code.
-- Press Ctrl+Shift+B (Windows) or Command+Shift+B (OSX) to start compiling the client and server in [watch mode](https://code.visualstudio.com/docs/editor/tasks#:~:text=The%20first%20entry%20executes,the%20HelloWorld.js%20file.).
-- Switch to the Run and Debug View in the Sidebar (Ctrl+Shift+D on Windows, Command+Shift+D on OSX).
-- Select `Launch Client` from the drop down (if it is not already).
-- Press ▷ to run the launch config (F5).
-
-### Testing
-
-- Run `npm install` in the root directory. This installs all necessary npm modules.
-- Run `npm run compile` to compile the code & client for testing.
-- Run `npm run test-node` to execute the client node test suite.
-
-#### Remote Testing the Web functionality
-
-- To manually test the extension in the browser for [VS Code for the Web](https://vscode.dev/) before publishing, follow [these instructions](https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension-in-vscode.dev) to setup a VS Code for the Web instance with your local extension, and then proceed with the normal testing flow.
+When ready to test, from the terminal, and while inside your working directory, run:
+```shell
+fga model test --tests=./store.yaml
+```
 
 ## Roadmap
 
 A rough [roadmap](https://github.com/orgs/openfga/projects/3) for development priorities.
 
 ## Contributing
 
-See [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md).
+See the [DEVELOPMENT](./docs/DEVELOPMENT.md) and [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md).
 
 ## Author
 

diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -0,0 +1,51 @@
+# Development and Contributing to the OpenFGA VS Code Extension
+
+Read the [OpenFGA Contribution Process](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md) and the [OpenFGA Code of Conduct](https://github.com/openfga/.github/blob/main/CODE_OF_CONDUCT.md).
+
+## Getting Started
+
+- Run `npm install` in the root directory. This installs all necessary npm modules.
+- Run `npm run compile && npm run test-node` to execute the client node test suite.
+
+## Distribution (Optional)
+
+To generate an installable build of this extension, you can do the following:
+
+- Run `npm install --global @vscode/vsce` to get the latest version of `vsce` for packaging 
+- Run `vsce package` to generate an installable `VISX` artifact for testing or distribution
+
+## Structure
+
+```
+.
+├── client // Language Client
+│   ├── src
+│   │   ├── test // End to End tests for Language Client / Server
+│   │   ├── extension.node.ts // Language Client node entry point
+│   │   └── extension.browser.ts // Language CLient web entry point
+├── package.json // The extension manifest.
+└── server // Language Server
+    └── src
+        ├── server.node.ts // Language Server node entry point
+        ├── server.browser.ts // Language Server web entry point
+        └── server.common.ts // Language Server common code
+```
+
+## Running the Client
+
+- Run `npm install` in the root directory. This installs all necessary npm modules.
+- Open the root directory in VS Code.
+- Press Ctrl+Shift+B (Windows) or Command+Shift+B (OSX) to start compiling the client and server in [watch mode](https://code.visualstudio.com/docs/editor/tasks#:~:text=The%20first%20entry%20executes,the%20HelloWorld.js%20file.).
+- Switch to the Run and Debug View in the Sidebar (Ctrl+Shift+D on Windows, Command+Shift+D on OSX).
+- Select `Launch Client` from the drop down (if it is not already).
+- Press ▷ to run the launch config (F5).
+
+## Testing
+
+- Run `npm install` in the root directory. This installs all necessary npm modules.
+- Run `npm run compile` to compile the code & client for testing.
+- Run `npm run test-node` to execute the client node test suite.
+
+### Remote Testing the Web functionality
+
+- To manually test the extension in the browser for [VS Code for the Web](https://vscode.dev/) before publishing, follow [these instructions](https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension-in-vscode.dev) to setup a VS Code for the Web instance with your local extension, and then proceed with the normal testing flow.