Initial commit

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "tuesday"
+    assignees:
+      - "joschka"
+    open-pull-requests-limit: 10

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+# setup the workflow trigger(s) according to your needs
+# see: https://docs.github.com/en/actions/using-workflows/triggering-a-workflow
+on:
+  push:
+    branches: ["main", "alpha", "beta", "next", "next-major"]
+  # manual
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org
+          scope: "@digitalservice4germany"
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - name: Release
+        run: cd dist && npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # create NPM_TOKEN repository secret (repo settings -> secrets and variables)
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 DigitalService
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,51 @@
+# npm package example 
+
+Minimal starting point for creating a DigitalService npm package, which you can release with one manual click or (if applicable) triggered automatically by an event. Requires consistent use of conventional commits!
+
+## Enabler: Conventional commits
+
+> The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
+
+source: [conventionalcommits.org](https://www.conventionalcommits.org/)
+
+Putting in the effort to write machine-readable commits at commit time frees one from creating a changelog and figuring out the next version number at release time. This makes releasing super simple and ensures that it happens often.
+
+## Assumption: Release from `dist` folder
+
+Assumption: you have some kind of build step and you want to release only your build artifact (`dist` folder). Make sure to have a `package.json` in the `dist` folder before releasing. Feel free to adapt if your package is different.
+
+## Good to know: Version in package.json
+
+The `"version"` field in the `package.json` *in the repository* is never updated. It's always `"0.0.0-development"`. The *published* `package.json` though has the correct current version. You never have to set a version string anywhere.
+
+## Good to have: npm package provenance
+
+It links packages to their source and build and increases trust in the supply chain. This is only possible when the `npm release` runs on GitHub Actions, not when you release on your local machine.
+
+Make sure to have the following configuration in your `package.json` to enable npm package provenance.
+
+```json
+"publishConfig": {
+    "provenance": true
+},
+```
+
+## Mandatory: Commit message linting
+
+Magically simple releasing only works with correct conventional commits. You must always use them! That's why linting is basically mandatory. This example uses `commitlint` with `lefthook` as one possible way.
+
+## Checklist when not using this template repository
+
+In case you just want to cherry pick for your existing package.
+
+* `package.json`: set `"version"` to `"0.0.0-development"` (optional, but recommended)
+* `package.json`: add `"publishConfig": { "provenance": true }` (optional, but recommended)
+* repository settings: add a `NPM_TOKEN` repository secret (repository -> settings -> secrets and variables -> actions -> new repository secret). Find the value in 1Password ("NPM"), look for "Publish Token," its value starts with "npm_"
+* copy `.github/workflows/release.yml` and adapt to your needs. Make sure to not remove permissions and to keep the configuration of the `setup-node` action.
+* `npm install --save-dev semantic-release`
+
+### For linting
+
+* `npm install --save-dev @commitlint/cli @commitlint/config-conventional` + configuration in `commitlint.config.js`
+* `npm install --save-dev lefthook` + configuration in `lefthook.yml`
+

commitlint.config.js

@@ -0,0 +1 @@
+module.exports = { extends: ["@commitlint/config-conventional"] };

lefthook.yml

@@ -0,0 +1,4 @@
+commit-msg:
+  commands:
+    "lint commit message":
+      run: npx commitlint --edit {1}