From 96b900e4cd407d7fe1f60f36528d78e95a51245a Mon Sep 17 00:00:00 2001 From: Andrea Luzzardi Date: Fri, 21 May 2021 15:02:18 -0700 Subject: [PATCH] ci: markdown lint Signed-off-by: Andrea Luzzardi --- .github/workflows/ci.yml | 6 ++++ .markdownlint.yaml | 5 +++ README.md | 24 +++++++------- docs/index.md | 3 +- docs/install.md | 6 ++-- docs/operator.md | 18 +++++------ docs/programming.md | 67 +++++++++++++++++++--------------------- docs/vs.md | 2 -- 8 files changed, 67 insertions(+), 64 deletions(-) create mode 100644 .markdownlint.yaml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2abcff98..a9a7d41c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,6 +40,12 @@ jobs: run: | make shellcheck cuelint check-buildkit-version + - name: Markdown Lint + uses: nosborn/github-action-markdown-cli@v1.1.1 + with: + files: ./docs README.md + config_file: ".markdownlint.yaml" + test: name: Test runs-on: ubuntu-latest diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..bedc3c97 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,5 @@ +# Default state for all rules +default: true + +# MD013/line-length - Line length +MD013: false diff --git a/README.md b/README.md index 40a1af6c..f56690cc 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,19 @@ Dagger is a programmable deployment system. -Using Dagger, software builders can automate the deployment of any application to any infrastructure, -in just a few lines of code. +Using Dagger, software builders can automate the deployment of any application +to any infrastructure, in just a few lines of code. ![image](https://user-images.githubusercontent.com/29565/112705398-d0222980-8e5b-11eb-98b9-32c117a3d606.jpeg) The Dagger platform adapts to your application, not the other way around. -Thanks to its ecosystem of reusable packages and flexible scripting system, Dagger can be dropped -into any software project without requiring changes to its architecture or workflow. -Think of it as your "devops superglu". +Thanks to its ecosystem of reusable packages and flexible scripting system, +Dagger can be dropped into any software project without requiring changes to +its architecture or workflow. Think of it as your "devops superglu". -No matter how your deployment works under the hood, you can manage it with the same Dagger user interface. -This makes developers more productive, because they don't have to learn a new workflow every time their deployment -system changes. +No matter how your deployment works under the hood, you can manage it with the +same Dagger user interface. This makes developers more productive, because they +don't have to learn a new workflow every time their deployment system changes. ## Learn More @@ -22,7 +22,6 @@ system changes. * [Dagger Programming Guide](doc/programming.md) * [Dagger Operator Manual](doc/operator.md) - ## Download and Install * [Install Dagger from source](doc/install.md) @@ -33,8 +32,9 @@ system changes. Join the [Dagger community chatroom](https://discord.gg/Rmffpmc) on Discord. We welcome beginners and experts alike! - ## Alpha disclaimer -Dagger is *alpha-quality software*. It has many bugs, the user interface is minimal, and it may change in incompatible ways at any time. If you are still willing to try it, thank you! We appreciate your help and encourage you to ask questions and report issues. - +Dagger is *alpha-quality software*. It has many bugs, the user interface is +minimal, and it may change in incompatible ways at any time. If you are still +willing to try it, thank you! We appreciate your help and encourage you to ask +questions and report issues. diff --git a/docs/index.md b/docs/index.md index 72f06d57..ed2a717b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,7 +33,6 @@ We welcome beginners and experts alike! ## Alpha disclaimer -Dagger is *alpha-quality software*. It has many bugs, the user interface is -minimal, and it may change in incompatible ways at any time. If you are still +Dagger is _alpha-quality software_. It has many bugs, the user interface is minimal, and it may change in incompatible ways at any time. If you are still willing to try it, thank you! We appreciate your help and encourage you to ask questions and report issues. diff --git a/docs/install.md b/docs/install.md index 46cecc10..258b90fe 100644 --- a/docs/install.md +++ b/docs/install.md @@ -55,19 +55,19 @@ From the **assets** section, download the archive corresponding to your OS and A You will need [Go](https://golang.org) version 1.16 or later. -1. Clone the dagger repository +1\. Clone the dagger repository ```shell git clone https://github.com/dagger/dagger.git ``` -2. Build the `dagger` binary. +2\. Build the `dagger` binary. ```shell cd dagger; make ``` -3. Copy the `dagger` tool to a location listed in your `$PATH`. For example, to copy it to `/usr/local/bin`: +3\. Copy the `dagger` tool to a location listed in your `$PATH`. For example, to copy it to `/usr/local/bin`: ```shell cp ./cmd/dagger/dagger /usr/local/bin diff --git a/docs/operator.md b/docs/operator.md index 2b67539f..d8e0a406 100644 --- a/docs/operator.md +++ b/docs/operator.md @@ -6,23 +6,22 @@ Dagger can be configured to use an existing buildkit daemon, running either loca To use a buildkit daemon listening on TCP port `1234` on localhost: -``` -$ export BUILDKIT_HOST=tcp://localhost:1234 +```shell +export BUILDKIT_HOST=tcp://localhost:1234 ``` To use a buildkit daemon running in a container named "super-buildkit" on the local docker host: -``` -$ export BUILDKIT_HOST=docker-container://super-buildkit +```shell +export BUILDKIT_HOST=docker-container://super-buildkit ``` To use a buildkit daemon running on a remote docker host (be careful to properly secure remotely accessible docker hosts!) +```shell +export BUILDKIT_HOST=docker-container://super-buildkit +export DOCKER_HOST=tcp://my-remote-docker-host:2376 ``` -$ export BUILDKIT_HOST=docker-container://super-buildkit -$ export DOCKER_HOST=tcp://my-remote-docker-host:2376 -``` - ## OpenTracing Support @@ -31,7 +30,7 @@ Both Dagger and buildkit support opentracing. To capture traces to A `docker-compose` file is available to help bootstrap the tracing environment: -```sh +```shell docker-compose -f ./tracing.compose.yaml up -d export JAEGER_TRACE=localhost:6831 export BUILDKIT_HOST=docker-container://dagger-buildkitd-jaeger @@ -40,4 +39,3 @@ dagger compute ... ``` You can then go to [http://localhost:16686/](http://localhost:16686/) in your browser to see the traces. - diff --git a/docs/programming.md b/docs/programming.md index 56d4be79..1365b923 100644 --- a/docs/programming.md +++ b/docs/programming.md @@ -8,7 +8,7 @@ ## Programming in Cue [Cue](https://cuelang.org) is a next-generation data language by Marcel van Lohuizen and the spiritual successor -of GCL, the language used to configure all of Google's infrastructure. +of GCL, the language used to configure all of Google's infrastructure. Cue extends JSON with powerful features: @@ -22,44 +22,44 @@ To get started with Cue, we recommend the following resources: * [Cuetorials](https://cuetorials.com) * [Cue playground](https://cuelang.org/play/) - ## Writing your first plan To create a Dagger plan: -1. Create a new directory anywhere in your git repository. +1\. Create a new directory anywhere in your git repository. For example: `mkdir staging`. -2. Create a new file with the *.cue* extension, and open it with any text editor or IDE. +2\. Create a new file with the *.cue* extension, and open it with any text editor or IDE. For example: `staging.cue`. -3. Describe each relay in your plan as a field in the cue configuration. +3\. Describe each relay in your plan as a field in the cue configuration. For example: -``` +```cue package main import ( - "dagger.io/docker" - "dagger.io/git" + "dagger.io/docker" + "dagger.io/git" ) // Relay for fetching a git repository repo: git.#Repository & { - remote: "https://github.com/dagger/dagger" - ref: "main" + remote: "https://github.com/dagger/dagger" + ref: "main" } // Relay for building a docker image ctr: docker.#Build & { - source: repo + source: repo } ``` For more inspiration, see these examples: + * [Deploy a static page to S3](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-static-page-to-s3) * [Deploy a simple React application](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-simple-react-application) * [Deploy a complete JAMstack app](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-complete-jamstack-app) @@ -67,41 +67,39 @@ For more inspiration, see these examples: * [Add HTTP monitoring to your application](https://github.com/dagger/dagger/blob/main/examples/README.md#add-http-monitoring-to-your-application) * [Deploy an application to your Kubernetes cluster](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-an-application-to-your-kubernetes-cluster) +4\. Extend your plan with relay definitions from [Dagger Universe](../stdlib), an encyclopedia of cue packages curated by the Dagger community. -4. Extend your plan with relay definitions from [Dagger Universe](../stdlib), an encyclopedia of cue packages curated by the Dagger community. - -5. If you can't find the relay you need in the Universe, you can simply create your own. +5\. If you can't find the relay you need in the Universe, you can simply create your own. For example: -``` +```cue import ( - "strings" + "strings" ) // Create a relay definition which generates a greeting message #Greeting: { - salutation: string | *"hello" - name: string | *"world" - message: "\(strings.ToTitle(salutation)), \(name)!" + salutation: string | *"hello" + name: string | *"world" + message: "\(strings.ToTitle(salutation)), \(name)!" } ``` You may then create any number of relays from the same definition: -``` +```cue french: #Greeting & { - salutation: "bonjour" - name: "monde" + salutation: "bonjour" + name: "monde" } american: #Greeting & { - salutation: "hi" - name: "y'all" + salutation: "hi" + name: "y'all" } ``` - ## Concepts ### Plans @@ -115,6 +113,7 @@ It lays out the application's supply chain as a graph of interconnected nodes: * Software dependencies: operating systems, languages, libraries, frameworks, etc. The graph models the flow of code and data through the supply chain: + * source code flows from a git repository to a build system; * system dependencies are combined in a docker image, then uploaded to a registry; * configuration files are generated then sent to a compute cluster or load balancer; @@ -122,7 +121,6 @@ The graph models the flow of code and data through the supply chain: Dagger plans are written in [Cue](https://cuelang.org), a powerful declarative language by the creator of GQL, the language used to deploy all applications at Google. - ### Environments An *environment* is a live implementation of a *plan*, with its own user inputs and state. @@ -144,6 +142,7 @@ Relays are standalone software components: they are defined in [Cue](https://cue execute code in any language using the [Dagger pipeline API](FIXME). A relay is made of 3 parts: + * Inputs: data received from the user, or upstream relays * A processing pipeline: code executed against each new input, using the [pipeline API](FIXME) * Outputs: data produced by the processing pipeline @@ -152,7 +151,6 @@ Relays run in parallel, with their inputs and outputs interconnected into a spec called a *DAG*. When a relay receives a new input, it runs it through the processing pipeline, and produces new outputs, which are propagated to downstream relays as inputs, and so on. - ### Using third-party relays Cue includes a complete package system. This makes it easy to create a complex plan in very few @@ -161,27 +159,26 @@ lines of codes, simply by importing relays from third-party packages. For example, to create a plan involving Github, Heroku and Amazon RDS, one might import the three corresponding packages: -``` +```cue import ( - "dagger.io/github" - "dagger.io/heroku" - "dagger.io/amazon/rds" + "dagger.io/github" + "dagger.io/heroku" + "dagger.io/amazon/rds" ) repo: github.#Repository & { - // Github configuration values + // Github configuration values } backend: heroku.#App & { - // Heroku configuration values + // Heroku configuration values } db: rds.#Database & { - // RDS configuration values + // RDS configuration values } ``` - ### Creating a new relay Sometimes there is no third-party relay available for a particular task in your workflow; or it may exist but need to be customized. diff --git a/docs/vs.md b/docs/vs.md index 808ecbb4..140c9a0a 100644 --- a/docs/vs.md +++ b/docs/vs.md @@ -1,6 +1,5 @@ # Dagger vs. Other Software - ## Dagger vs. PaaS (Heroku, Firebase, etc.) *Summary: Dagger can be used with or without a PaaS system.* @@ -12,7 +11,6 @@ A PaaS system is a complete platform for deploying and running certain types of As an application grows, it is almost certain to outgrow the capabilities of a PaaS system, leaving no choice but to look for alternatives. A good strategy is to choose the right platform for each component. Some components continue to run on a PaaS system; others run on specialized infrastructure. This strategy can be implemented with Dagger: each component gets its own deployment plan expressed as code, and Dagger glues it all together into a single workflow. - ## Dagger vs. artisanal deploy scripts *Summary: Dagger can augment your deploy scripts, and later help you simplify or even remove them.*