docs: update readme and add examples

README.md

@@ -5,120 +5,134 @@
 
 Common and Reusable GitHub Actions for the GEWIS organization.
 
-## Docker build
-Workflow for building a docker image.
+> [!NOTE]  
+> All inputs for the workflows should be provided as strings. However, sometimes a certain structure is expected. These are noted in the "Options" columns.
+
+## Lint and build
+Workflow for linting, formatting, testing and building projects. Can be used for both `npm` and `yarn`.
 
-### Example
 ```yaml
-name: Docker Build
+jobs:
+  build-and-lint-yarn:
+    uses: GEWIS/actions/.github/workflows/lint-and-build-npm.yml@v1.0.0
+    with:
+      node-version: '22.x'
+      format: true
+
+  build-and-lint-npm:
+    uses: GEWIS/actions/.github/workflows/lint-and-build-yarn.yml@v1.0.0
+    with:
+      node-version: '20.x'
+      test: true
+```
+
+### Inputs
+
+| Input name        | Description                                                  | Required | Options                | Default value |
+|-------------------|--------------------------------------------------------------|----------|------------------------|---------------|
+| working-directory | The directory where the project is located.                  | ☐ |                        | `.`           |
+| node-version      | The version of Node.js to use.                               | ☐ | `18.x`, `20.x`, `22.x` | `20.x`        |
+| artifact-name     | The name of the artifact to use.                             | ☐ |                        |               |
+| artifact-path     | The path where the artifact should be stored.                | ☐ |                        |               |
+| prepare-command   | The command to run before building (and and after checkout). | ☐ |                        |               |
+| cleanup-command   | The command to run after building.                           | ☐ |                        |               |
+| lint              | Whether to lint the project.                                 | ☐ | `true`, `false`        | `true`        |
+| format            | Whether to format the project.                               | ☐ | `true`, `false`        | `false`       |
+| test              | Whether to run tests.                                        | ☐ | `true`, `false`        | `false`       |
+| build             | Whether to build the project.                                | ☐ | `true`, `false`        | `true`        |
 
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
+## Docker build
+Workflow for building a docker image. Useful for, for example, testing if a container build succeeds on a develop branch.
 
+```yaml
 jobs:
   dockerize:
-    uses: GEWIS/actions/.github/workflows/docker-build.yml@v0.0.2
+    uses: GEWIS/actions/.github/workflows/docker-build.yml@v1.0.0
     with:
       projects: '["."]'
 ```
 
-
-## Semantic release
-Workflow for building Docker images and releasing them. Includes versioning using `semantic-release-action`.
-
 ### Inputs
 
-| Input name      | Description                                              | Required | Types/values | Default value |
-|-----------------|----------------------------------------------------------|----------|--------------|---------------|
-| projects        | A comma-separated list of projects to release.           | ☑ | `string`     | N/A           |
-| docker-registry | The docker registry to push the build image to.          | ☑ | `string`     | N/A           |
-| docker-paths    | The docker namespace, project and image name to push to. | ☑ | `string`     | N/A           |
-| env_file        | Contents of the environment file to use during building. | ☐ | `string`     | N/A           |
+| Input name | Description                                  | Required | Options | Default value |
+|------------|----------------------------------------------|----------|---------|---------------|
+| projects   | Comma-separated list of projects to release. | ☑ |         |               |
 
-### Secrets
-| Secret name       | Secret value                               | 
-|-------------------|--------------------------------------------|
-| REGISTRY_USERNAME | The username used to push to the registry. | 
-| REGISTRY_PASSWORD | The password used to push to the registry. |
-### Example
+## Docker release
+Workflow for building Docker images and releasing them. Can be used to push to GitHub and any other registry.
 
 ```yaml
-name: Semantic release
-
-on:
-  pull_request:
-    branches: 
-    - main
-
 jobs:
   build-and-lint:
-    uses: GEWIS/actions/.github/workflows/semantic-release.yml@v0.0.2
+    uses: GEWIS/actions/.github/workflows/docker-release.yml@v1.0.0
     with:
       projects: '["."]'
-      docker_registry: 'abc.docker-registry.gewis.nl'
-      docker_tag: 'nc/aurora/core'
+      docker-registry: 'abc.docker-registry.gewis.nl'
+      docker-path: 'nc/aurora/core'
+      version: '4.0.40'
+      github-registry: 'true'
 ```
 
-## Lint and build
-Workflow for linting, formatting, testing and building Typescript projects.
-
 ### Inputs
 
-| Input name        | Description                                                  | Required | Types/values           | Default value |
-|-------------------|--------------------------------------------------------------|----------|------------------------|---------------|
-| working-directory | The directory where the TypeScript project is located.       | ☐ | `string`               | `.`           |
-| node-version      | The version of Node.js to use.                               | ☐ | `18.x`, `20.x`, `22.x` | `20.x`        |
-| package-manager   | The package manager to use.                                  | ☐ | `npm`, `yarn`          | `npm`         |
-| artifact-name     | The name of the artifact to use.                             | ☐ | `string`               | N/A           |
-| artifact-path     | The path where the artifact should be stored.                | ☐ | `string`               | N/A           |
-| prepare-command   | The command to run before building (and and after checkout). | ☐ | `string`               | N/A           |
-| cleanup-command   | The command to run after building.                           | ☐ | `string`               | N/A           |
-| lint              | Whether to lint the project.                                 | ☐ | `boolean`              | `true`        |
-| format            | Whether to format the project.                               | ☐ | `boolean`              | `false`       |
-| test              | Whether to run tests.                                        | ☐ | `boolean`              | `false`       |
-| build             | Whether to build the project.                                | ☐ | `boolean`              | `true`        |
-
-### Example
+| Input name      | Description                                              | Required | Options         | Default value |
+|-----------------|----------------------------------------------------------|----------|-----------------|---------------|
+| projects        | Comma-separated list of projects to release.             | ☑ |                 |               |
+| version         | Version of the Docker release.                           | ☑ |                 |               |
+| docker-registry | The docker registry to push the build image to.          | ☑ |                 |               |
+| github-registry | Whether to push the image to the GitHub registry.        | ☐ | `true`, `false` | `false`       |
+| env-file        | Contents of the environment file to use during building. | ☐ |                 |               |
+| docker-paths    | The docker namespace, project and image name to push to. | ☑ |                 |               |
 
-```yaml
-name: Lint and build
+### Secrets
 
-on:
-  push:
-    branches: 
-    - develop
-  pull_request:
-    branches: 
-    - develop
+| Secret name        | Secret value                                      | 
+|--------------------|---------------------------------------------------|
+| REGISTRY\_USERNAME | The username used to push to the custom registry. | 
+| REGISTRY\_PASSWORD | The password used to push to the custom registry. |
 
+## NPM release
+Workflow for releasing a NPM package on GitHub.
+
+```yaml
 jobs:
   build-and-lint:
-    uses: GEWIS/actions/.github/workflows/typescript-lint-and-build.yml@v0.0.2
+    uses: GEWIS/actions/.github/workflows/npm-release.yml@v1.0.0
     with:
-      node-version: '22.x'
-      package-manager: 'yarn'
-      format: true
+      version: '4.0.40'
+      lerna: 'true'
 ```
 
+### Inputs
+
+| Input name   | Description                             | Required | Options                | Default value |
+|--------------|-----------------------------------------|----------|------------------------|---------------|
+| node-version | The version of Node.js to use.          | ☐ | `18.x`, `20.x`, `22.x` | `20.x`        |
+| version      | Version of the NPM release.             | ☑ |                        |               |
+| lerna        | Whether the project is a lerna project. | ☐ | `true`, `false`        | `false`       |
+
+
 ## Versioning
 Workflow for versioning a project using `semantic-release-action`.
 
-### Example
 ```yaml
-name: Versioning
-
-on:
-  pull_request:
-    branches: 
-    - main
-
 jobs:
   build-and-lint:
-    uses: GEWIS/actions/.github/workflows/versioning.yml@v0.0.2
+    uses: GEWIS/actions/.github/workflows/versioning.yml@v1.0.0
 ```
 
+### Inputs
+
+| Input name | Description                                          | Required | Options  | Default value |
+|------------|------------------------------------------------------|----------|----------|---------------|
+| dry-run    | Whether to run a dry run of the semantic versioning. | ☐ | `string` | `.`           |
+
+### Outputs
+
+| Output name  | Description                               | Options  | Default value |
+|--------------|-------------------------------------------|----------|---------------|
+| next-version | The next semantic version of the project. | `string` | ""            |
+
+## Examples
+
+Example workflows for building, versioning and releasing a project can be found in the [examples](./examples) directory.

examples/docker-build.yml

@@ -0,0 +1,15 @@
+name: Docker Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  dockerize:
+    uses: GEWIS/actions/.github/workflows/docker-build.yml@1.0.0
+    with:
+      projects: '["."]'

examples/lint-and-build.yml

@@ -0,0 +1,19 @@
+name: Lint and build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-and-lint:
+    uses: GEWIS/actions/.github/workflows/typescript-lint-and-build.yml@1.0.0
+    with:
+      node-version: "22.x"
+      package-manager: "yarn"
+      lint: true
+      format: true
+      build: true

examples/npm-semantic-release.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    push:
+      branches:
+        - 'main'
+    pull_request:
+      branches:
+        - 'main'
+
+jobs:
+  versioning:
+    uses: GEWIS/actions/.github/workflows/npm-release.yml@1.0.0
+    with:
+      dry-run: 'true',
+
+  publish-npm:
+    uses: GEWIS/actions/.github/workflows/npm-release.yml@1.0.0
+    needs: versioning
+    if: ${{ needs.versioning.outputs.next_version != '' }}
+    with:
+      node-version: '22.x'
+      version: ${{ needs.versioning.outputs.next_version }}
+      lerna: 'true'

examples/semantic-release.yml

@@ -0,0 +1,18 @@
+name: Semantic release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  semantic-release:
+    uses: GEWIS/actions/.github/workflows/semantic-release.yml@1.0.0
+    with:
+      projects: "['.']"
+      docker_registry: "abc.docker-registry.gewis.nl"
+      docker_paths: "['eou/plankapi']"
+      github-registry: "true"
+    secrets:
+      REGISTRY_USERNAME: ${{ secrets.SVC_GH_ABCEOU_USERNAME }}
+      REGISTRY_PASSWORD: ${{ secrets.SVC_GH_ABCEOU_PWD }}