fix: rewrite readme docs for yarn packaging, added CI script for pull…

… requests Signed-off-by: Ben Meier <ben.meier@humanitec.com>
score-spec · Jun 20, 2024 · d065ba6 · d065ba6
1 parent dd76111
commit d065ba6
Show file tree

Hide file tree

Showing 49 changed files with 550 additions and 755 deletions.
diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml
@@ -0,0 +1,24 @@
+name: Release to Dev Environment
+
+on:
+  pull_request:
+    branches: [ "*" ]
+    paths-ignore:
+      - README.md
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v4
+      - run: npm install -g yarn
+      - run: yarn install
+      - run: yarn run hugo
+      - run: yarn run dprint check
+  try-build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v2
+      - run: docker build .
diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,7 @@
-FROM klakegg/hugo:ext-alpine
+FROM hugomods/hugo:exts-0.123.8 as docsy
 
-RUN apk add git && \
-  git config --global --add safe.directory /src
+COPY . /src
+WORKDIR /src
+RUN npm install --production=false
+
+CMD [ "hugo", "server", "--themesDir", "../..", "--disableFastRender", "--renderToMemory", "--bind", "0.0.0.0" ]
diff --git a/Dockerfile-publish b/Dockerfile-publish
diff --git a/README.md b/README.md
@@ -7,24 +7,32 @@ For information on Score's style guide see the [Style guide](styles/style-guide.
 
 ### Running the website locally
 
-Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
-You can find out more about how to install Hugo for your environment in our
-[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
+We use `yarn` (for MacOS: `brew install yarn`) as a package manager to ensure the versions of Hugo and associated tools are up to date. All commands that execute those tools are prefixed with `yarn run` or are aliased in the `package.json` file.
 
-From the repo root folder, run:
+To install the packages:
 
-To use yarn.
+```
+yarn install
+```
+
+To run the server locally:
 
-```bash
-yarn build
 ```
+yarn build
 
-To use Hugo.
+OR
 
-```bash
-hugo server -D
+yarn run hugo server
 ```
 
+And then view it at <http://localhost:1313>.
+
+### Deployment
+
+_NOTE_: we want to change this to be statically rendered and deployed with github pages if we can.
+
+Deployment currently runs by building and deploying the [Dockerfile](Dockerfile) to a container runtime. The hosting is currently provided by Humanitec.
+
 ### Format docs
 
 The following section covers how to format and lint prose.
@@ -42,20 +50,16 @@ yarn fmt
 Example output.
 
 ```bash
-$ dprint fmt
+$ yarn fmt
 Formatted 1 file.
 ✨  Done in 0.13s.
 ```
 
 This project uses the [Vale](https://vale.sh) with a [Vale-compatible implementation of the Google Developer Documentation Style Guide](https://github.com/errata-ai/Google).
 
-To lint your doc run:
+On MacOS, install it through `brew install vale`.
 
-```bash
-yarn fmt /path/to/your/file.md
-```
-
-For example, to lint this document run:
+For example, to lint a document run:
 
 ```bash
 vale sync
@@ -72,45 +76,12 @@ Example output.
 ✖ 1 error, 0 warnings and 0 suggestions in 1 file.
 ```
 
+To lint all documents, run `yarn lint`.
+
 ## Troubleshooting documentation site builds
 
 This section covers common build issues with Hugo.
 
-### Extended version of Hugo
-
-As you run the website locally, you may run into the following error:
-
-```bash
-➜ hugo server
-
-INFO 2021/01/21 21:07:55 Using config file:
-Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
-Built in 288 ms
-Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
-```
-
-This error occurs if you have not installed the extended version of Hugo.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
-
-Or you may encounter the following error:
-
-```bash
-➜ hugo server
-
-Error: failed to download modules: binary with name "go" not found
-```
-
-This error occurs if you have not installed the `go` programming language on your system.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
-
-[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
-[deploys]: https://app.netlify.com/sites/docsy-example/deploys
-[docsy user guide]: https://docsy.dev/docs
-[docsy]: https://github.com/google/docsy
-[example.docsy.dev]: https://example.docsy.dev
-[hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
-[netlify]: https://netlify.com
-
 ### Failed to resolve output format `print`
 
 When building the server, you may receive the following error message.

diff --git a/content/en/docs/How to/environment-variables.md b/content/en/docs/How to/environment-variables.md
@@ -13,7 +13,7 @@ aliases:
 
 You can pass environment-specific configuration to the container during a deployment. The Score Specification enables a special `environment` resource type to be used to support such use cases.
 
-Environment configurations are set within the [`resource`]({{< relref "/docs/score-specification/score-spec-reference" >}} "Container") section of your Score Specification file. These act as environment variables when you're deploying a Workload.
+Environment configurations are set within the [`resource`]({{< relref "/docs/score specification/score-spec-reference" >}} "Container") section of your Score Specification file. These act as environment variables when you're deploying a Workload.
 
 Values for those variables can be either hard-coded (not recommended) or sourced from the resources properties through substitutions (recommended) such as `${resources.my-db.host}`.
 
@@ -22,4 +22,4 @@ The Score Specification supports declaring environment variables in a configurat
 For more information, see
 
 - [Environment variables in score-compose](https://github.com/score-spec/score-compose/tree/main/examples/02-environment)
-- [Environment variables in score-helm](https://github.com/score-spec/score-helm/tree/main/examples/02-environment)
+- [Environment variables in score-helm](https://github.com/score-spec/score-helm/tree/main/examples/02-environment)
diff --git a/content/en/docs/How to/overrides.md b/content/en/docs/How to/overrides.md
@@ -77,4 +77,4 @@ Set the path of the property to an empty value to remove the property.
 score-compose run -f score.yaml --override-property metadata.my-service=
 ```
 
-For more information, please refer to the score-compose [examples library](https://github.com/score-spec/score-compose/tree/main/examples/07-overrides#overriding-individual-properties-in-the-score-file).
+For more information, please refer to the score-compose [examples library](https://github.com/score-spec/score-compose/tree/main/examples/07-overrides#overriding-individual-properties-in-the-score-file).
diff --git a/content/en/docs/get started/_index.md b/content/en/docs/get started/_index.md
@@ -76,10 +76,10 @@ Congrats! You’ve successfully run your first Score Implementation with a Hello
 
 ## Next steps
 
-* **Explore more examples**: Check out the [examples folder](https://github.com/score-spec/score-compose/tree/main/examples) for score-compose to dive into further use cases and experiment with different configurations.
+- **Explore more examples**: Check out the [examples folder](https://github.com/score-spec/score-compose/tree/main/examples) for score-compose to dive into further use cases and experiment with different configurations.
 
-* **Learn more about score-compose**: Investigate the inner workings of the score-compose reference implementation by exploring its CLI reference [here](/docs/score-implementation/score-compose#cli-reference).
+- **Learn more about score-compose**: Investigate the inner workings of the score-compose reference implementation by exploring its CLI reference [here](/docs/score-implementation/score-compose#cli-reference).
 
-* **Explore other implementations**: Play around with [other available open-source Score implementations](/docs/score-implementation/). For example, you could continue by running the same Score file used in the example above via the score-k8s CLI to generate a Kubernetes manifest.
+- **Explore other implementations**: Play around with [other available open-source Score implementations](/docs/score-implementation/). For example, you could continue by running the same Score file used in the example above via the score-k8s CLI to generate a Kubernetes manifest.
 
-* **Join the Score community Slack**: If you encounter any issues or have questions, feel free to reach out to us in the [Score community Slack](https://join.slack.com/t/scorecommunity/shared_invite/zt-2a0x563j7-i1vZOK2Yg2o4TwCM1irIuA).
+- **Join the Score community Slack**: If you encounter any issues or have questions, feel free to reach out to us in the [Score community Slack](https://join.slack.com/t/scorecommunity/shared_invite/zt-2a0x563j7-i1vZOK2Yg2o4TwCM1irIuA).
diff --git a/content/en/docs/glossary/index.md b/content/en/docs/glossary/index.md
@@ -10,4 +10,4 @@ card:
   name: reference
   weight: 10
   title: Glossary
----
+---
diff --git a/content/en/docs/overview/_index.md b/content/en/docs/overview/_index.md
@@ -59,17 +59,17 @@ service:
 
 The Score specification is characterised by being:
 
-* **platform-agnostic**: The Score Specification is not tied to a specific platform, allowing integration with various container orchestration platforms and tooling such as Docker Compose, Kubernetes, Helm, or Google Cloud Run.
+- **platform-agnostic**: The Score Specification is not tied to a specific platform, allowing integration with various container orchestration platforms and tooling such as Docker Compose, Kubernetes, Helm, or Google Cloud Run.
 
-* **environment-agnostic**: The `score.yaml` file captures the configuration that stays the same across all environments. This allows combining it with environment-specific parameters in the target environment. For instance, the parameterized database connection string in the example above is intended to be resolved in each target environment by injecting the corresponding values.
+- **environment-agnostic**: The `score.yaml` file captures the configuration that stays the same across all environments. This allows combining it with environment-specific parameters in the target environment. For instance, the parameterized database connection string in the example above is intended to be resolved in each target environment by injecting the corresponding values.
 
-* **tightly scoped**: Score describes workload level properties. It does not intend to be a fully featured YAML replacement for any platform. Instead, Score draws a line between developer-owned workload configuration and platform-owned infrastructure configuration.
+- **tightly scoped**: Score describes workload level properties. It does not intend to be a fully featured YAML replacement for any platform. Instead, Score draws a line between developer-owned workload configuration and platform-owned infrastructure configuration.
 
-* **declarative**: Developers declare what their workload requires to run as part of `score.yaml`. The platform in the target environment is responsible for resolving individual runtime requirements.
+- **declarative**: Developers declare what their workload requires to run as part of `score.yaml`. The platform in the target environment is responsible for resolving individual runtime requirements.
 
 ## How does Score work?
 
-The Score Specification can be run against a Score Implementation (CLI) such as [score-compose](/docs/score-implementation/score-compose) or [score-k8s](/docs/score-implementation/score-k8s/) to generate a platform configuration file such as `docker-compose.yaml` or a Kubernetes `manifest.yaml` file. 
+The Score Specification can be run against a Score Implementation (CLI) such as [score-compose](/docs/score-implementation/score-compose) or [score-k8s](/docs/score-implementation/score-k8s/) to generate a platform configuration file such as `docker-compose.yaml` or a Kubernetes `manifest.yaml` file.
 
 The generated configuration file can then be combined with environment-specific parameters to run the workload in the target environment.
 
@@ -80,12 +80,15 @@ For more hands-on examples, visit the [examples library](https://github.com/scor
 ## Benefits
 
 ### Reduces cognitive load
+
 Score reduces cognitive load by providing a single, easy to understand specification file that allows to run the same workload on entirely different technology stacks without the developer needing to be an expert in any one of them. Developers no longer have to fight a bunch of tech and tools when promoting their workloads from local to production, and can instead focus on writing and deploying code.
 
 ### Eliminates configuration mismanagement
+
 Development teams risk configuration inconsistencies when promoting workloads between environments that run on different technology stacks. For example, if you're running a testing environment with Docker Compose and a production environment on Kubernetes, keeping your Wwrkloads' configuration in sync can be challenging as each platform comes with its own set of APIs, semantics, syntax and configuration constructs. With Score, developers describe their workloads once with `score.yaml` and any required platform-specific configuration can be automatically generated via a Score Implementation (e.g. score-compose or score-k8s). This significantly reduces the risk of configuration mismatch between environments.
 
 ### Enables separation of concerns
+
 Score enables a clear separation of concerns between developer-owned Workload related configuration and platform-owned infrastructure related configuration: Developers describe what their Wwrkload requires to run as part of `score.yaml` and if the requirements are honored by the platform, the workload runs as intended.
 
 ## What Score is not

diff --git a/content/en/docs/overview/score-for-devs.md b/content/en/docs/overview/score-for-devs.md
@@ -2,7 +2,7 @@
 title: "Score for developers"
 linkTitle: "Score for developers"
 description: Learn about Score as a developer
-weight: 1
+weight: 2
 Focus_Keyword: "Learn about Score as a developer"
 
 ---
@@ -13,8 +13,7 @@ Score is a workload specification designed to simplify development for cloud-nat
 
 Below you'll find an example of a simple Score application with a web server that queries a Postgres database on each request. The demo code can be found [here](https://github.com/score-spec/sample-app-gif).
 
-
-``` yaml
+```yaml
 # The version string helps identify the Score file syntax
 apiVersion: score.dev/v1b1
 metadata:
@@ -88,4 +87,4 @@ Score is designed by developers for developers. We’ll spare you the usual mark
 
 Score is open source! Connect with fellow Score developers on our [Slack](https://join.slack.com/t/scorecommunity/shared_invite/zt-2a0x563j7-i1vZOK2Yg2o4TwCM1irIuA) or browse through our [GitHub repository](https://github.com/score-spec/spec) to see what’s new, or start your own implementation project.
 
-Got something to say about Score? [We're all ears](https://github.com/score-spec/spec?tab=readme-ov-file#-get-involved)! We’d love to discuss your ideas on where the project should go next or how we can improve.
+Got something to say about Score? [We're all ears](https://github.com/score-spec/spec?tab=readme-ov-file#-get-involved)! We’d love to discuss your ideas on where the project should go next or how we can improve.
diff --git a/content/en/docs/score implementation/Other/_index.md b/content/en/docs/score implementation/Other/_index.md
@@ -3,4 +3,4 @@ title: "Available implementation CLIs"
 linkTitle: "Other"
 weight: 3
 description: "An overview of open-source Score implementation CLIs"
----
+---
diff --git a/content/en/docs/score implementation/Other/included/_index.md b/content/en/docs/score implementation/Other/included/_index.md
@@ -3,4 +3,4 @@ title: "score-helm installation"
 headless: true
 toc_hide: true
 hide_summary: true
----
+---
diff --git a/content/en/docs/score implementation/Other/included/install-score-helm-bash.md b/content/en/docs/score implementation/Other/included/install-score-helm-bash.md
@@ -55,4 +55,4 @@ The command returns the following output:
 score-helm x.y.z
 ```
 
-You’ve successfully installed the score-helm CLI!
+You’ve successfully installed the score-helm CLI!
diff --git a/content/en/docs/score implementation/Other/included/install-wget-helm.md b/content/en/docs/score implementation/Other/included/install-wget-helm.md
@@ -63,4 +63,4 @@ The command returns the following output:
 score-helm <x.y.z>
 ```
 
-You've successfully installed the score-helm CLI!
+You've successfully installed the score-helm CLI!
diff --git a/content/en/docs/score implementation/Other/included/install-windows.md b/content/en/docs/score implementation/Other/included/install-windows.md
@@ -9,4 +9,4 @@ toc_hide: true
 
 **2.** Decompress the `zip` file, and move the binary to your `PATH`.
 
-You've successfully installed the score-helm CLI!
+You've successfully installed the score-helm CLI!
diff --git a/content/en/docs/score implementation/Other/score-helm.md b/content/en/docs/score implementation/Other/score-helm.md
@@ -12,9 +12,9 @@ aliases:
 
 The score-helm CLI allows developers to translate their Score specification into Helm values files. Below you'll find an overview of:
 
-* [Installation options](#installation)
-* [CLI reference](#cli-reference)
-* [Examples](#examples)
+- [Installation options](#installation)
+- [CLI reference](#cli-reference)
+- [Examples](#examples)
 
 For additional details and opportunities to contribute to the project, visit the [score-helm](https://github.com/score-spec/score-helm) GitHub repository.
 
@@ -126,7 +126,7 @@ Help for the `run` command.
 score-helm run -h
 ```
 
-#### `--output`  | `-o`
+#### `--output` | `-o`
 
 The output location of the helm file. Uses the default value `./helm.yaml` if the flag isn't specified.
 
@@ -168,4 +168,4 @@ score-helm run -f ./score.yaml -o ./values.yaml --verbose
 
 Explore examples for score-helm in the [examples library](https://github.com/score-spec/score-helm/tree/main/examples) on GitHub.
 
-If you encounter any issues or have questions, feel free to reach out to us in the [Score community Slack](https://join.slack.com/t/scorecommunity/shared_invite/zt-2a0x563j7-i1vZOK2Yg2o4TwCM1irIuA).
+If you encounter any issues or have questions, feel free to reach out to us in the [Score community Slack](https://join.slack.com/t/scorecommunity/shared_invite/zt-2a0x563j7-i1vZOK2Yg2o4TwCM1irIuA).
diff --git a/content/en/docs/score implementation/Other/score-humanitec.md b/content/en/docs/score implementation/Other/score-humanitec.md
@@ -15,4 +15,4 @@ The Humanitec Platform Orchestrator offers native support for Score, enabling th
 
 For detailed instructions on usage and configuration, please refer to the [Humanitec developer documentation](https://developer.humanitec.com/score/overview/#how-do-score-and-the-platform-orchestrator-work-together).
 
-If you have any questions or concerns regarding this implementation, feel free to [reach out to the Humanitec team directly](https://developer.humanitec.com/support/contact).
+If you have any questions or concerns regarding this implementation, feel free to [reach out to the Humanitec team directly](https://developer.humanitec.com/support/contact).
diff --git a/content/en/docs/score implementation/_index.md b/content/en/docs/score implementation/_index.md
@@ -5,4 +5,4 @@ weight: 3
 aliases:
 - /docs/reference/score-cli/
 - /docs/get-started/install
----
+---
diff --git a/content/en/docs/score implementation/included/install-score-compose-bash.md b/content/en/docs/score implementation/included/install-score-compose-bash.md
@@ -55,4 +55,4 @@ The command returns the following output:
 score-compose x.y.z
 ```
 
-You’ve successfully installed the score-compose CLI!
+You’ve successfully installed the score-compose CLI!
diff --git a/content/en/docs/score implementation/included/install-score-compose-curl-mac.md b/content/en/docs/score implementation/included/install-score-compose-curl-mac.md
@@ -38,4 +38,4 @@ sudo mv ./score-compose /usr/local/bin/score-compose
 sudo chown root: /usr/local/bin/score-compose
 ```
 
-You’ve successfully installed the score-compose CLI!
+You’ve successfully installed the score-compose CLI!
diff --git a/content/en/docs/score implementation/included/install-score-k8s-bash.md b/content/en/docs/score implementation/included/install-score-k8s-bash.md
@@ -55,4 +55,4 @@ The command returns the following output:
 score-k8s x.y.z
 ```
 
-You’ve successfully installed the score-k8s CLI!
+You’ve successfully installed the score-k8s CLI!
diff --git a/content/en/docs/score implementation/included/install-score-k8s-curl-mac.md b/content/en/docs/score implementation/included/install-score-k8s-curl-mac.md
@@ -38,4 +38,4 @@ sudo mv ./score-k8s /usr/local/bin/score-k8s
 sudo chown root: /usr/local/bin/score-k8s
 ```
 
-You’ve successfully installed the score-k8s CLI!
+You’ve successfully installed the score-k8s CLI!
diff --git a/content/en/docs/score implementation/included/install-windows-compose.md b/content/en/docs/score implementation/included/install-windows-compose.md
@@ -9,4 +9,4 @@ toc_hide: true
 
 **2.** Decompress the `zip` file, and move the binary to your `PATH`.
 
-You've successfully installed the score-compose CLI!
+You've successfully installed the score-compose CLI!
diff --git a/content/en/docs/score implementation/included/install-windows-k8s.md b/content/en/docs/score implementation/included/install-windows-k8s.md
@@ -9,4 +9,4 @@ toc_hide: true
 
 **2.** Decompress the `zip` file, and move the binary to your `PATH`.
 
-You've successfully installed the score-k8s CLI!
+You've successfully installed the score-k8s CLI!