Merge pull request #169 from github/cschleiden/update-readmes

Add/update package readmes
2023-03-01 08:19:27 -08:00
parent 2a420e29f6 6bbd3dda95
commit aaa59885af
4 changed files with 128 additions and 13 deletions
@@ -1,6 +1,6 @@
-# actions-expressions
+# actions/expressions

-`actions-expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions).
+`@actions/expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions).

 ## Installation

@@ -1,4 +1,4 @@
-# actions-languageserver
+# actions/languageserver

 `actions-languageserver` hosts the `actions-languageservice` and makes it available via the [language server protocol](https://microsoft.github.io/language-server-protocol/) (LSP) as a standalone language server.

@@ -1,4 +1,4 @@
-# actions-languageservice
+# actions/languageservice

 This package contains the logic for the GitHub Actions workflows language server.

@@ -22,14 +22,6 @@ The language service features use three sources of information:
 * _value providers_ which can dynamically add values to the schema, for example, the list of available labels for a repository when validating `runs-on`.
 * _context providers_ which can dynamically provide available contexts used in [expressions](https://docs.github.com/actions/reference/context-and-expression-syntax-for-github-actions#about-contexts-and-expressions). For example, the contents of the `github.event` context for a given workflow file.

-##### Value Providers
-
-TODO
-
-##### Context Providers
-
-TODO
-
 #### Validation

 Validate a workflow file, returns an array of [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnostic) objects.
@@ -60,7 +52,43 @@ const hover = await hover(document, {line: 0, character: 1}); // { contents: { k

 #### Auto-completion

-TODO
+```typescript
+import {complete} from "@actions/languageservice";
+
+const document = {
+  uri: "file:///path/to/file",
+  getText: () => `on: 
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - run: echo hello`
+};
+
+// Trigger completion for `on: |`
+const suggestions = await complete(document, {line: 0, character: 4});
+```
+
+will return
+
+```jsonc
+[{
+  "documentation": {
+    "kind": "markdown",
+    "value": "Runs your workflow when branch protection rules in the workflow repository are changed.",
+  },
+  "label": "branch_protection_rule",
+  "textEdit": {
+    "newText": "branch_protection_rule",
+    "range": {
+      "end": {"character": 4, "line": 0,},
+      "start": {"character": 4, "line": 0},
+    },
+  },
+},
+//... other events
+]
+```

 ## Contributing

@@ -0,0 +1,87 @@
+# actions/workflow-parser
+
+`@actions/workflow-parser` is a library to parse GitHub Actions [workflows](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions).
+
+## Installation
+
+The [package](https://www.npmjs.com/package/@actions/workflow-parser) contains TypeScript types and compiled ECMAScript modules.
+
+```bash
+npm install @actions/workflow-parser
+```
+
+## Usage
+
+The parser is driven by a custom schema defined in [`worflows-v1.0.json`](./src/workflow-v1.0.json).
+
+### Simple example
+
+`parseWorkflow` parses the workflow YAML into an intermediate representation and validates that it conforms to the schema. Any parsing errors are returned in the `errors` property of the result context.
+
+```typescript
+var trace: TraceWriter;
+
+const result = parseWorkflow(
+  {
+    name: "test.yaml",
+    content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - run: echo 'hello'`
+  },
+  trace
+);
+```
+
+`convertWorkflowTemplate` then takes that intermediate representation and converts it to a [`WorkflowTemplate`](./src/workflow-template.ts) object, which is a more convenient representation for working with workflows.
+
+```typescript
+const workflowTemplate = await convertWorkflowTemplate(result.context, result.value);
+
+// workflowTemplate.jobs[0].id === "build"
+// workflowTemplate.jobs[0].steps[0].run === "echo 'hello'"
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.
+
+Similar to [`actions/expressions](../expressions/), this project is just one of multiple implementations of the GitHub Actions workflow parser. We therefore cannot accept contributions that significantly modify the schema or the overall behavior of the parser. If you would like to propose changes to Actions itself, please use our [Community Forum](https://github.com/community/community/discussions/categories/actions-and-packages).
+
+If you do want to contribute, please run [prettier](https://prettier.io/) to format your code and add unit tests as appropriate before submitting your PR. [./testdata](./testdata) contains test cases that all implementations should pass, please also make sure those tests are still passing.
+
+### Build
+
+```bash
+npm run build
+```
+
+or to watch for changes
+
+```bash
+npm run watch
+```
+
+### Test
+
+```bash
+npm test
+```
+
+or to watch for changes and run tests:
+
+```bash
+npm run test-watch
+```
+
+### Lint
+
+```bash
+npm run format-check
+```
+
+## License
+
+This project is licensed under the terms of the MIT open source license. Please refer to [MIT](../LICENSE) for the full terms.