diff --git a/lit/docs/auth.lit b/lit/docs/auth.lit
index ffde6ecc..a0f0911c 100644
--- a/lit/docs/auth.lit
+++ b/lit/docs/auth.lit
@@ -3,11 +3,11 @@
\use-plugin{concourse-docs}
\split-sections
-A single Concourse installation can accomodate many projects and users.
+A single Concourse installation can accommodate many projects and users.
Pipelines, builds, and all other user data are owned by \italic{teams}. A team
-is just a conceptual owner and a separate namespace, tied to an authorization
-config. For example, a team may authorize all members of the \code{concourse}
+is simply a conceptual owner and separate namespace, tied to an authorization
+configuration. For example, a team may authorize all members of the \code{concourse}
GitHub organization to be a \reference{team-member-role}{member}.
When a user authenticates, each team's authorization config is checked against
@@ -29,37 +29,36 @@ access control for future requests.
users, see \reference{fly-expose-pipeline}.
Even with a pipeline exposed, all build logs are hidden by default. This is
- because CI jobs are prone to leaking credentials and other...unsavory
- information. After you've determined that a job's builds should be safe for
- public consumption, you can set \reference{schema.job.public}{\code{public: true}}
- on the job in your pipeline.
+ because CI jobs may leak credentials and other sensitive information.
+ After you've determined that a job's builds are safe for public consumption,
+ you can set \reference{schema.job.public}{\code{public: true}} on the job
+ in your pipeline.
}
\section{
\title{Security Caveats}{teams-caveats}
- At present, teams only provide \italic{trusted multi-tenancy}. This means it
+ At present, teams only provide \italic{trusted multi-tenancy}. This means they
should be used for cases where you know and trust who you're allowing access
into your Concourse cluster.
- There are a few reasons it'd be a bad idea to do otherwise:
+ There are a few reasons it would be a bad idea to do otherwise:
\list{
- Any team can run builds with \reference{schema.task.privileged} tasks. A bad
- actor in the mix could easily use this to harm your workers and your
+ Any team can run builds with \reference{schema.task.privileged} tasks. A malicious
+ actor could easily use this to harm your workers and your
cluster.
- In the future, we'll probably have this as a flag on a team, indicating
+ In the future, we'll likely add this as a flag on a team, indicating
whether they're permitted to run privileged builds.
}{
There are no networking restrictions in place, and traffic to and from the
workers is currently unencrypted and unauthorized. Anyone could run a task
- that does horrible things to your worker's containers, possibly stealing
+ that does harmful things to your worker's containers, potentially stealing
sensitive information.
This can be remedied with configuration specified on Garden to restrict
access to the internal network, but this is not detailed in our docs, and
- we'll probably want to find a better answer than configuration in the
- future.
+ we'll likely want to find a better solution in the future.
}
-}
+}
\ No newline at end of file
diff --git a/lit/docs/builds.lit b/lit/docs/builds.lit
index 729ad866..27d06832 100644
--- a/lit/docs/builds.lit
+++ b/lit/docs/builds.lit
@@ -2,7 +2,7 @@
\use-plugin{concourse-docs}
-A build is an execution of a \italic{build plan}, which is either
+A build is an execution of a \italic{build plan}, which is either:
\list{
configured as a sequence of \reference{steps}{steps} in a \reference{jobs}{job}
@@ -14,25 +14,25 @@ A build is an execution of a \italic{build plan}, which is either
Containers and volumes are created as \reference{get-step}s,
\reference{put-step}s, and \reference{task-step}s run. When a build completes
-successfully, these containers go away.
+successfully, these containers are removed.
-A failed build's containers and volumes are kept around so that you can debug
-the build via \reference{fly-intercept}. If the build belongs to a
-\reference{jobs}{job}, the containers will go away when the next build starts.
-If the build is a one-off, its containers will be removed immediately, so make
-sure you intercept while it's running, if you want to debug.
+For failed builds, containers and volumes are preserved to allow debugging
+via \reference{fly-intercept}. If the build belongs to a
+\reference{jobs}{job}, the containers will be removed when the next build starts.
+If the build is a one-off, its containers will be removed immediately, so make sure
+you intercept while it's running if you want to debug.
\table-of-contents
\section{
\title{Rerunning a Build}{build-rerunning}
- Concourse supports build rerunning, which means to run a new build using the
+ Concourse supports build rerunning, which means running a new build using the
exact same set of input versions as the original build. There are two ways to
rerun a build: through the web UI on the builds page and through the
- \reference{fly-rerun-build}.
+ \reference{fly-rerun-build} command.
- When a build is rerun, it will create a new build using the name of the
+ When a build is rerun, it creates a new build using the name of the
original build with the rerun number appended to it, e.g. \code{3.1} for the
first rerun of build \code{3}.
@@ -40,11 +40,11 @@ sure you intercept while it's running, if you want to debug.
than becoming a new "latest" build. Similarly, when the scheduler is
resolving \reference{schema.get.passed}{\code{passed}} constraints
that reference a job with rerun builds, those rerun builds are
- processed in this same order. This ensures that the versions, which made it
- through a rerun build, do not become the new "latest versions". Instead, they
+ processed in this same order. This ensures that versions which made it
+ through a rerun build do not become the new "latest versions". Instead, they
act as if the original build had succeeded at its point in the build history.
- This may sound a little confusing, but the summary is that reruns should
+ This may sound a little confusing, but the key point is that reruns should
behave as if they replace the original failed build.
\section{
@@ -56,11 +56,11 @@ sure you intercept while it's running, if you want to debug.
with.
This means that if the \reference{schema.job.plan} has changed in a way
- that is backwards-incompatible, the rerun build may error. For example, if
+ that is backwards-incompatible, the rerun build may fail. For example, if
a new input is added, its version will not be available as the original
build did not use it.
- There are future plans to have reruns execute the exact build plan from the
+ There are plans to have reruns execute the exact build plan from the
original build. If you are interested in tracking the progress for the
second pass at rerunning builds - or contributing yourself! - the project
epic is called \link{Build Lifecycle
@@ -86,7 +86,7 @@ sure you intercept while it's running, if you want to debug.
This can be useful for periodically monitoring the state of a job. The output
also works well with tools like \code{awk} and \code{grep}.
- By default the most recent 50 builds are shown. To see more builds, use
+ By default, the most recent 50 builds are shown. To see more builds, use
the \code{-c} flag, like so:
\codeblock{bash}{{
@@ -97,16 +97,16 @@ sure you intercept while it's running, if you want to debug.
\section{
\title{\code{fly intercept}}{fly-intercept}
- Sometimes it's helpful to connect to the machine where tasks run. This way you
- can either profile or inspect tasks, or see the state of the machine at the
- end of a run. Due to Concourse running tasks in containers on remote
- machines this would typically be hard to access.
+ Sometimes it's helpful to connect to the machine where tasks run. This allows you
+ to profile or inspect tasks, or see the state of the machine at the
+ end of a run. Since Concourse runs tasks in containers on remote
+ machines, these would typically be difficult to access.
- To this end, there is a \code{fly intercept} command that will give you an
+ The \code{fly intercept} command gives you an
interactive shell inside the specified container. Containers are identified
- by a few things, so you may need to specify a few flags to hone down the
- results. If there are multiple containers that the flags could refer to, an
- interactive prompt will show up allowing you to disambiguate.
+ by several attributes, so you may need to specify multiple flags to narrow down the
+ results. If there are multiple matching containers, an
+ interactive prompt will appear allowing you to select one.
For example, running the following will run a task and then enter the
finished task's container:
@@ -118,15 +118,15 @@ sure you intercept while it's running, if you want to debug.
\aside{
When intercepting a task running on a Windows worker, you will need to
- specifically tell fly to to run \code{powershell}:
+ specifically tell fly to run \code{powershell}:
\codeblock{bash}{{
$ fly -t example intercept powershell
}}
}
- Containers are around for a short time after a build finishes in order to
- allow people to intercept them.
+ Containers remain available for a short time after a build finishes to
+ allow for interception.
You can also intercept builds that were run in your pipeline. By using
\code{--job}, \code{--build}, and \code{--step} you can intercept a specific
@@ -138,11 +138,11 @@ sure you intercept while it's running, if you want to debug.
}}
Note that \code{--build} can be omitted, and will default to the most recent
- build of the job. One-off builds can be reached by passing in their build ID
- to \code{--build} which can be found on the build list page.
+ build of the job. One-off builds can be reached by passing their build ID
+ to \code{--build}, which can be found on the build list page.
- The \code{--step} flag can also be omitted; this will let you pick the step
- interactively, if you don't know the exact name.
+ The \code{--step} flag can also be omitted; this will let you select the step
+ interactively if you don't know the exact name.
Resource checking containers can also be intercepted with \code{--check} or
\code{-c}:
@@ -157,7 +157,7 @@ sure you intercept while it's running, if you want to debug.
current build's task, even as the "current build" changes.
The working directory and any relevant environment variables (e.g. those
- having come from \reference{schema.task.params}) used by the original process will
+ from \reference{schema.task.params}) used by the original process will
also be used for the process run by intercept.
}
@@ -178,26 +178,26 @@ sure you intercept while it's running, if you want to debug.
\title{\code{fly watch}}{fly-watch}
Concourse emits streaming colored logs on the website, but it can be helpful
- to have the logs available to the command line (e.g. so that they can be
+ to have the logs available in the command line (e.g. so they can be
processed by other commands).
- The \code{watch} command can be used to do just this. You can also view
+ The \code{watch} command can be used for this purpose. You can view
builds that are running in your pipeline, or builds that have already
finished.
Note that unlike \reference{fly-execute}, killing \code{fly watch} via
\code{SIGINT} or \code{SIGTERM} will \italic{not} abort the build.
- To watch the most recent one-off build, just run \code{fly watch} with no
- arguments. To watch a specific build (one-off or no), pass \code{--build}
+ To watch the most recent one-off build, run \code{fly watch} with no
+ arguments. To watch a specific build (one-off or not), pass \code{--build}
with the ID of the build to watch. This ID is available at the start of
\reference{fly-execute}'s output or by browsing to the builds list in the web
UI.
- By using the \code{--job} and \code{--build} flags you can pick out a
+ By using the \code{--job} and \code{--build} flags, you can select a
specific build of a job to watch. For example, the following command will
- either show the archived logs for an old build, if it has finished running, or
- it will stream the current logs, if the build is still in progress.
+ either show the archived logs for an old build if it has finished running, or
+ it will stream the current logs if the build is still in progress.
\codeblock{bash}{{
$ fly -t example watch --job my-pipeline/tests --build 52
@@ -206,5 +206,7 @@ sure you intercept while it's running, if you want to debug.
If the \code{--job} flag is specified and \code{--build} is omitted, the most
recent build of the specified job will be selected.
- If there is a mismatch between the \code{fly} and \code{web} versions, it is possible to run into \code{failed to parse next event: unknown event type} error. The \code{--ignore-event-parsing-errors} flag can be passed to ignore such errors.
-}
+ If there is a mismatch between the \code{fly} and \code{web} versions, you may encounter
+ a \code{failed to parse next event: unknown event type} error. The \code{--ignore-event-parsing-errors}
+ flag can be passed to ignore such errors.
+}
\ No newline at end of file
diff --git a/lit/docs/config.lit b/lit/docs/config.lit
index df8c9328..a3cd4497 100644
--- a/lit/docs/config.lit
+++ b/lit/docs/config.lit
@@ -2,16 +2,16 @@
\use-plugin{concourse-docs}
-Concourse configuration for things like \reference{pipelines} and
-\reference{tasks} is done through declarative
+Concourse configuration for features like \reference{pipelines} and
+\reference{tasks} is managed through declarative
\link{YAML}{https://en.wikipedia.org/wiki/YAML} files.
-Concourse configuration supports basic variable substitution by way of
+Concourse configuration supports basic variable substitution using
\reference{vars}{\code{((vars))}}. There is no built-in support for
-fancier templating constructs, e.g. loops and conditionals; users are free to
-use whatever templating system they like.
+more advanced templating constructs such as loops and conditionals; users are free to
+use whatever templating system they prefer.
\table-of-contents
\include-section{config/yaml.lit}
-\include-section{config/basic-schemas.lit}
+\include-section{config/basic-schemas.lit}
\ No newline at end of file
diff --git a/lit/docs/getting-started.lit b/lit/docs/getting-started.lit
index bcd085cc..d861f5fa 100644
--- a/lit/docs/getting-started.lit
+++ b/lit/docs/getting-started.lit
@@ -1,10 +1,10 @@
\title{Getting Started}
-This tutorial will guide you through the basics of creating Concourse
+This tutorial guides you through the basics of creating Concourse
pipelines. You will use a local instance of Concourse running on your machine to
run pipelines.
-Before getting started you should have the following installed:
+Before getting started, ensure you have the following installed:
\list{
\link{Docker}{https://docs.docker.com/get-docker/}
@@ -13,17 +13,17 @@ Before getting started you should have the following installed:
}
This tutorial assumes you understand what Linux containers are and how to work
-with them. If you know what a Dockerfile is and how to make your own then you're
-probably good to jump into this tutorial. If you're not familiar with Linux
-containers then you may want to \link{get started with
-Docker}{https://docs.docker.com/get-started/} first before diving into this
+with them. If you know what a Dockerfile is and how to create one, you're
+probably ready for this tutorial. If you're not familiar with Linux
+containers, we recommend \link{getting started with
+Docker}{https://docs.docker.com/get-started/} before diving into this
tutorial.
It will also help if you know how to read YAML. We have a quick
\reference{intro-to-yaml} if you're not familiar with the syntax.
\aside{
- If you have any feedback for this tutorial please share it in \link{this
+ If you have any feedback for this tutorial, please share it in \link{this
GitHub discussion}{https://github.com/concourse/concourse/discussions/7353}
}
@@ -34,4 +34,4 @@ It will also help if you know how to read YAML. We have a quick
\include-section{getting-started/quickstart.lit}
\include-section{getting-started/hello-world.lit}
\include-section{getting-started/inputs-outputs.lit}
-\include-section{getting-started/resources.lit}
+\include-section{getting-started/resources.lit}
\ No newline at end of file
diff --git a/lit/docs/how-to-guides.lit b/lit/docs/how-to-guides.lit
index 1df6b22b..b6c513d3 100644
--- a/lit/docs/how-to-guides.lit
+++ b/lit/docs/how-to-guides.lit
@@ -1,14 +1,14 @@
\title{How-To Guides}
-The following pages are guides that show how to accomplish certain workflows
-within Concourse. Most of the guides will use specific images but you are in no
-way limited to or forced to use these images to accomplish the same task. There
-are many ways to accomplish the same thing in Concourse, so don't let these
-guides limit you in what you think is possible with Concourse.
+The following pages provide guides that show how to accomplish specific workflows
+within Concourse. Most guides use specific images, but you are not limited to
+or required to use these images to accomplish the same tasks. There are many ways
+to accomplish the same goal in Concourse, so don't let these guides limit your
+understanding of what's possible with Concourse.
\split-sections
\table-of-contents
\include-section{./guides/pipeline-guides.lit}
\include-section{./guides/git.lit}
-\include-section{./guides/container-images.lit}
+\include-section{./guides/container-images.lit}
\ No newline at end of file
diff --git a/lit/docs/install.lit b/lit/docs/install.lit
index 8a614ce5..9ba8ba66 100644
--- a/lit/docs/install.lit
+++ b/lit/docs/install.lit
@@ -2,24 +2,24 @@
\use-plugin{concourse-docs}
-A Concourse installation is composed of a \reference{web-node}, a
+A Concourse installation consists of a \reference{web-node}, a
\reference{worker-node}, and a \reference{postgresql-node}.
-There are many ways to deploy Concourse, depending on your personal preference.
-The \reference{quick-start} guide shows how to get Concourse up and running
+There are several ways to deploy Concourse, depending on your preference.
+The \reference{quick-start} guide shows how to get Concourse running
quickly via Docker Compose, and there is also an official \link{Concourse Helm
chart}{https://github.com/concourse/concourse-chart}.
-The documentation found here will primarily focus on the \code{concourse} CLI,
-which is the lowest common denominator, and can also be directly used if you
-want to just run Concourse yourself on real hardware or your own managed VMs.
+The documentation here primarily focuses on the \code{concourse} CLI,
+which is the lowest common denominator. You can use it directly if you want to
+run Concourse yourself on physical hardware or your own managed VMs.
-The high-level steps to follow for installing Concourse are:
+Follow these high-level steps to install Concourse:
\ordered-list{
- Setup a Postgres database
+ Set up a Postgres database
}{
- Generate Secrets for the web and worker nodes
+ Generate secrets for the web and worker nodes
}{
Install the web node
}{
@@ -27,7 +27,8 @@ The high-level steps to follow for installing Concourse are:
}
\aside{
- We don't document every configuration option for the \code{web} and \code{worker} commands. To view all flags you can run the following \code{docker} commands.
+ We don't document every configuration option for the \code{web} and \code{worker} commands.
+ To view all flags, you can run these \code{docker} commands:
\codeblock{bash}{{
docker run -t concourse/concourse web --help
@@ -44,4 +45,4 @@ The high-level steps to follow for installing Concourse are:
\include-section{install/generating-keys.lit}
\include-section{install/web.lit}
\include-section{install/worker.lit}
-\include-section{install/upgrading.lit}
+\include-section{install/upgrading.lit}
\ No newline at end of file
diff --git a/lit/docs/observation.lit b/lit/docs/observation.lit
index d5d9b77c..1f4982d9 100644
--- a/lit/docs/observation.lit
+++ b/lit/docs/observation.lit
@@ -2,7 +2,7 @@
\title{Observation}{observation}
-This section outlines everything you need to know for observing the state of
+This section outlines everything you need to know for monitoring the state of
your pipelines.
\section{
@@ -51,7 +51,7 @@ your pipelines.
\image{https://ci.concourse-ci.org/api/v1/teams/main/pipelines/concourse/jobs/unit/badge}
- If you want to have the image link to your pipeline/job in a README, you can make it like so:
+ If you want the image to link to your pipeline/job in a README, use HTML:
\codeblock{html}{{{
<a href="https://ci.concourse-ci.org/teams/main/pipelines/concourse/jobs/unit/badge">
@@ -65,4 +65,4 @@ your pipelines.
Pipelines may be exposed so that they can be monitored without having to
authenticate. For more information, see \reference{exposing}.
-}
+}
\ No newline at end of file
diff --git a/lit/docs/operation.lit b/lit/docs/operation.lit
index a0ec65c8..8b02d83e 100644
--- a/lit/docs/operation.lit
+++ b/lit/docs/operation.lit
@@ -1,11 +1,11 @@
\title{Operation}{operation}
-The following sections describes operator-focused features and tools that
+The following sections describe operator-focused features and tools that
Concourse provides, such as monitoring and credential management.
-These concepts are not required to operate Concourse, but are for users that
+These concepts are not required to operate Concourse, but are useful for users who
are looking to extend the capabilities of managing a Concourse deployment. For
-users that are new to these concepts, we do recommend learning how to set up
+users who are new to these concepts, we recommend learning how to set up
\reference{creds} and \reference{encryption}.
\split-sections
@@ -20,4 +20,4 @@ users that are new to these concepts, we do recommend learning how to set up
\include-section{./operation/opa.lit}
\include-section{./operation/performance-tuning.lit}
\include-section{./operation/global-resources.lit}
-\include-section{./operation/administration.lit}
+\include-section{./operation/administration.lit}
\ No newline at end of file
diff --git a/lit/docs/pipelines.lit b/lit/docs/pipelines.lit
index 7c2dd8b0..29afd588 100644
--- a/lit/docs/pipelines.lit
+++ b/lit/docs/pipelines.lit
@@ -5,8 +5,8 @@
A pipeline is the result of configuring \reference{jobs} and
\reference{resources} together. When you configure a pipeline, it takes on a
-life of its own, to continuously detect resource versions and automatically
-queue new builds for jobs as they have new available inputs.
+life of its own, continuously detecting resource versions and automatically
+queuing new builds for jobs as they have new available inputs.
Pipelines are configured via \reference{fly-set-pipeline} or the
\reference{set-pipeline} as declarative \reference{intro-to-yaml}{YAML
@@ -35,7 +35,7 @@ files} which conform to the following schema:
A list of job groups to use for organizing jobs in the web UI.
Groups have no functional effect on your pipeline. They are purely for
- making it easier to grok large pipelines in the web UI.
+ making it easier to understand large pipelines in the web UI.
Note: once you have added groups to your pipeline, all jobs must be in a
group.
@@ -59,7 +59,7 @@ files} which conform to the following schema:
This would display two tabs at the top of the home page: "test" and
"publish".
- For a real world example of how groups can be used to simplify navigation
+ For a real-world example of how groups can be used to simplify navigation
and provide logical grouping, see the groups used at the top of the page
in the \link{Concourse pipeline}{https://ci.concourse-ci.org}.
}
@@ -72,8 +72,8 @@ files} which conform to the following schema:
\optional-attribute{jobs}{[job.name]}{
A list of jobs that should appear in this group. A job may
- appear in multiple groups. Neighbours of jobs in the current group will also
- appear on the same page in order to give context of the location of the
+ appear in multiple groups. Neighbors of jobs in the current group will also
+ appear on the same page to provide context of the location of the
group in the pipeline.
You may also use any valid \link{glob}{https://www.man7.org/linux/man-pages/man7/glob.7.html}
@@ -99,7 +99,7 @@ files} which conform to the following schema:
\code{deploy-dev}, \code{deploy-staging}. The \code{ship} group will only match
\code{deploy-prod}. The \code{all} group will match all jobs in the pipeline.
- \warn{Note that depending on how it's used, \code{*}, \code{\{}, and
+ \warn{Note that depending on how they're used, \code{*}, \code{\{}, and
\code{\}} have special meaning in YAML, and may need to be quoted (as
was done in the \code{all} job above)}
}
@@ -168,8 +168,8 @@ files} which conform to the following schema:
\example{Small Go Project}{
When it comes to real-world projects, task configs are usually stored
- alongside the code that it's testing. This makes the pipeline a bit
- smaller and makes the config able to change without needing to
+ alongside the code being tested. This makes the pipeline
+ more concise and allows the config to change without needing to
reconfigure the pipeline.
\codeblock{yaml}{{
@@ -231,7 +231,7 @@ files} which conform to the following schema:
\reference{resource-types}{Resource Types} can be used to extend the
functionality of your pipeline and provide deeper integrations. This
example uses one to trigger a job whenever a new \link{Dinosaur
- Comic}{http://www.qwantz.com} is out.
+ Comic}{http://www.qwantz.com} is published.
\codeblock{yaml}{{{
---
@@ -255,4 +255,4 @@ files} which conform to the following schema:
trigger: true
}}}
}
-}
+}
\ No newline at end of file
diff --git a/lit/docs/resource-types.lit b/lit/docs/resource-types.lit
index 61f6fec4..7d7b00c3 100644
--- a/lit/docs/resource-types.lit
+++ b/lit/docs/resource-types.lit
@@ -7,9 +7,9 @@ what versions are detected, the bits that are fetched when the resource's
\reference{get-step} runs, and the side effect that occurs when the resource's
\reference{put-step} runs.
-Concourse comes with a few "core" resource types to cover common use cases like
+Concourse comes with several "core" resource types to cover common use cases like
\code{git} and \code{s3} - the rest are developed and supported by the
-Concourse community. An exhaustive list of all resource types is available in
+Concourse community. A comprehensive list of all resource types is available in
the \link{Resource Types catalog}{https://resource-types.concourse-ci.org}.
A pipeline's resource types are listed under
@@ -54,24 +54,24 @@ A pipeline's resource types are listed under
containers will be run with full capabilities, as determined by the worker
backend the task runs on.
- For Linux-based backends it typically determines whether or not the
+ For Linux-based backends, it typically determines whether or not the
container will run in a separate user namespace, and whether the
\code{root} user is "actual" \code{root} (if set to \code{true}) or a user
namespaced \code{root} (if set to \code{false}, the default).
- This is a gaping security hole; only configure it if the resource type needs
- it (which should be called out in its documentation). This is not up to the
- resource type to decide dynamically, so as to prevent privilege escalation
+ This is a significant security risk; only configure it if the resource type needs
+ it (which should be noted in its documentation). This is not up to the
+ resource type to decide dynamically, to prevent privilege escalation
via third-party resource type exploits.
}
\optional-attribute{params}{config}{
- Arbitrary config to pass when running the \code{get} to fetch the resource
+ Arbitrary configuration to pass when running the \code{get} to fetch the resource
type's image.
}
\optional-attribute{check_every}{duration}{
- \italic{Default \code{1m}.} The interval on which to check for new versions
+ \italic{Default \code{1m}.} The interval at which to check for new versions
of the resource type. Acceptable interval options are defined by the
\link{time.ParseDuration
function}{https://golang.org/pkg/time/#ParseDuration}.
@@ -120,8 +120,8 @@ A pipeline's resource types are listed under
}
\example-toggle{Overriding default resource types}{
- Since it's possible to overwrite the base resource types, it can be
- used to give defaults to resources at the pipeline level.
+ Since it's possible to overwrite the base resource types, this can be
+ used to provide defaults to resources at the pipeline level.
\codeblock{yaml}{{{
resource_types:
@@ -150,7 +150,7 @@ A pipeline's resource types are listed under
\reference{resource-types}{Resource Types} can be used to extend the
functionality of your pipeline and provide deeper integrations. This
example uses one to trigger a job whenever a new \link{Dinosaur
- Comic}{http://www.qwantz.com} is out.
+ Comic}{http://www.qwantz.com} is published.
\codeblock{yaml}{{{
---
@@ -162,7 +162,7 @@ A pipeline's resource types are listed under
tag: latest
resources:
- - name: booklit-releases
+ - name: dinosaur-comics
type: rss
source:
url: http://www.qwantz.com/rssfeed.php
@@ -170,7 +170,7 @@ A pipeline's resource types are listed under
jobs:
- name: announce
plan:
- - get: booklit-releases
+ - get: dinosaur-comics
trigger: true
}}}
}
diff --git a/lit/docs/resources.lit b/lit/docs/resources.lit
index 22558d52..65b73196 100644
--- a/lit/docs/resources.lit
+++ b/lit/docs/resources.lit
@@ -3,13 +3,13 @@
\use-plugin{concourse-docs}
\split-sections
-Resources are the heart and soul of Concourse. They represent all external
+Resources are the foundation of Concourse. They represent all external
inputs to and outputs of \reference{jobs}{jobs} in the pipeline.
Each resource represents a versioned artifact with an external source of truth.
Configuring the same resource in any pipeline on any Concourse cluster will
-behave the exact same way. Concourse will continuously \code{check} each
-configured resource to discover new versions. These versions then flow through
+function in an identical way. Concourse will continuously \code{check} each
+configured resource to detect new versions. These versions then flow through
the pipeline via \reference{get-step}s configured on \reference{jobs}.
A pipeline's resources are listed under \reference{schema.pipeline.resources}
@@ -28,7 +28,7 @@ with the following schema.
\required-attribute{source}{config}{
The configuration for the resource. This varies by resource type, and is a black
- box to Concourse; it is blindly passed to the resource at runtime.
+ box to Concourse; it is simply passed to the resource at runtime.
To use \code{git} as an example, the source may contain the repo URI, the
branch of the repo to track, and a private key to use when pushing/pulling.
@@ -43,7 +43,7 @@ with the following schema.
\optional-attribute{old_name}{identifier}{
The old name of the resource. If configured, the history of the old resource will be
- inherited to the new one. Once the pipeline is set, this field can be
+ carried over to the new one. Once the pipeline is set, this field can be
removed as the history has been transferred.
\example-toggle{Renaming a resource}{
@@ -71,7 +71,7 @@ with the following schema.
\optional-attribute{icon}{string}{
The name of a \link{Material Design icon}{https://materialdesignicons.com/}
- to show next to the resource name in the web UI. For example,
+ to display next to the resource name in the web UI. For example,
\code{github}.
}
@@ -113,7 +113,7 @@ with the following schema.
\optional-attribute{tags}{[string]}{
\italic{Default \code{[]}.} A list of tags to determine which workers the
- checks will be performed on. You'll want to specify this if the source is
+ checks will be performed on. This is useful if the source is
internal to a worker's network, for example.
\warn{
@@ -128,8 +128,8 @@ with the following schema.
version of the resource will be viewable by unauthenticated users (assuming
the pipeline has been \reference{exposing}{exposed}).
- Resource metadata should never contain credentials or secret information, but
- this is off by default just to be safe in case users don't want to show
+ Resource metadata should never contain credentials or private information, but
+ this is off by default just to be safe in case users don't want to reveal
things like commit messages and authors to the public.
Note: even when set to \code{false}, the versions identifiers will be
@@ -139,11 +139,11 @@ with the following schema.
\optional-attribute{webhook_token}{string}{
If specified, web hooks can be sent to trigger an immediate \italic{check}
- of the resource, specifying this value as a primitive form of
+ of the resource, using this value as a simple form of
authentication via query params.
After configuring this value, you would then configure your hook sender with
- the following painfully long path appended to your external URL:
+ the following path appended to your external URL:
\code{{
/api/v1/teams/TEAM_NAME/pipelines/PIPELINE_NAME/resources/RESOURCE_NAME/check/webhook?webhook_token=WEBHOOK_TOKEN
@@ -214,7 +214,7 @@ with the following schema.
This could be passed to a job via a \reference{get-step} with
\reference{schema.get.trigger}{\code{trigger: true}} to run the job
- periodically:
+ regularly:
\codeblock{yaml}{{{
resources:
@@ -231,4 +231,4 @@ with the following schema.
config: # ...
}}}
}
-}
+}
\ No newline at end of file
diff --git a/lit/docs/steps.lit b/lit/docs/steps.lit
index b94c4702..ac50829c 100644
--- a/lit/docs/steps.lit
+++ b/lit/docs/steps.lit
@@ -66,7 +66,7 @@ by configuring \reference{schema.on_failure} or
copy of the bits in their working directory.
\example-toggle{Fetching a repo and passing it to a task}{
- Almost every simple job will look something like this: fetch my code
+ Almost every simple job will look something like this: fetch your code
with a \reference{get-step} and do something (run tests) with it in a
\reference{task-step}.
@@ -201,7 +201,7 @@ by configuring \reference{schema.on_failure} or
\code{lvl-2-integration}) will be passed to \code{lvl-3-production}.
This is crucial to being able to implement safe "fan-in" semantics as
- things progress through a pipeline.
+ resources progress through a pipeline.
}
}
@@ -271,7 +271,7 @@ by configuring \reference{schema.on_failure} or
\italic{Default \code{latest}.} The version of the resource to fetch.
If set to \code{latest}, scheduling will just find the latest available
- version of a resource and use it, allowing versions to be skipped. This is
+ version of a resource and use it, allowing versions to be skipped. This is
usually what you want, e.g. if someone pushes 100 git commits.
If set to \code{every}, builds will walk through all available versions of
@@ -294,7 +294,7 @@ by configuring \reference{schema.on_failure} or
\schema-group{\code{put} step}{put}{
\required-attribute{put}{resource.name | identifier}{
- When the step succeeds, the version by the step will be immediately
+ When the step succeeds, the version created by the step will be immediately
fetched via an additional implicit \reference{get-step}. This is so
that later steps in your plan can use the artifact that was produced.
The artifact will be available under the identifier \code{put}
@@ -370,7 +370,7 @@ by configuring \reference{schema.on_failure} or
If configured as a list of identifiers, only the listed artifacts will
be provided to the container.
- If set to \code{detect}, the artifacts are detected based on the
+ If set to \code{detect}, the artifacts are determined based on the
configured \reference{schema.put.params} by looking for all string values
and using the first path segment as an identifier. (This may become the
default in the future.)
@@ -450,7 +450,7 @@ by configuring \reference{schema.on_failure} or
by setting \code{get_params}. For example, if you did not want a \code{put}
step utilizing the \link{ \code{registry-image} resource
type}{https://github.com/concourse/registry-image-resource} to download the
- image, you would implement your \code{put} step as such:
+ image, you would implement your \code{put} step as follows:
\codeblock{yaml}{{{
plan:
@@ -480,8 +480,8 @@ by configuring \reference{schema.on_failure} or
\reference{put-step}s to access the result of a task.
\required-attribute{task}{identifier}{
- The identifier value is just a name - short and sweet. The value is
- shown in the web UI but otherwise has no affect on anything. This may
+ The identifier value is just a name - short and descriptive. The value is
+ shown in the web UI but otherwise has no effect on anything. This may
change in the future; \link{RFC
#32}{https://github.com/concourse/rfcs/pull/32} proposes that the name
be used to reference a file within the project.
@@ -546,7 +546,7 @@ by configuring \reference{schema.on_failure} or
public: true
plan:
- task: simple-task
- config: # contains all field in a task config
+ config: # contains all fields in a task config
platform: linux
image_resource:
type: registry-image
@@ -637,7 +637,7 @@ by configuring \reference{schema.on_failure} or
with escalated capabilities available on the task's platform.
\warn{
- Setting \code{privileged: true} is a gaping security hole; use wisely
+ Setting \code{privileged: true} is a significant security risk; use wisely
and only if necessary. This is not part of the task configuration in
order to prevent privilege escalation via pull requests changing the
task file.
@@ -806,7 +806,7 @@ by configuring \reference{schema.on_failure} or
Total CPU shares declared: 4
}}}
- If you introduce another container then the number of CPU time per
+ If you introduce another container then the allocation of CPU time per
container changes. CPU shares are relative to each other.
\codeblock{}{{{
Container A: 2 shares - 25% CPU
@@ -961,7 +961,7 @@ by configuring \reference{schema.on_failure} or
automatically archived in the following scenarios:
\list{
When the job that previously set a pipeline runs a successful build
- which did not configure the pipeline (i.e. the \code{set_pipeline}
+ which did not configure the pipeline (i.e. the \code{set_pipeline}
step was removed for that specific pipeline).
}{
When the job is removed from its pipeline configuration (see
@@ -1100,7 +1100,7 @@ by configuring \reference{schema.on_failure} or
}}}
}
\example-toggle{Configuring instance vars and vars}{
- Both \code{instance_vars} and \code{vars} may be statically. The
+ Both \code{instance_vars} and \code{vars} may be set statically. The
difference between the two fields is that \code{instance_vars} are
used to identify a pipeline and render the pipeline config.
\code{vars} are only used for rendering the pipeline config:
@@ -1131,7 +1131,7 @@ by configuring \reference{schema.on_failure} or
\optional-attribute{vars}{vars}{
A map of template variables to pass to the pipeline config. Unlike
\reference{schema.set-pipeline.instance_vars}{\code{instance_vars}},
- \code{vars} are solely used to for
+ \code{vars} are solely used for
\reference{pipeline-static-vars}{interpolation}, and do not become a part of
the pipeline's identifier.
@@ -1202,7 +1202,7 @@ by configuring \reference{schema.on_failure} or
The \code{team} attribute can be used to specify another team.
Only the \reference{main-team} is allowed to set another team's
- pipeline. Any team other than the \reference{main-team} using the
+ pipeline. Any team other than the \reference{main-team} using the
\code{team} attribute will error, unless they reference their own team.
\warn{
diff --git a/lit/docs/tasks.lit b/lit/docs/tasks.lit
index 9b70e331..39d96444 100644
--- a/lit/docs/tasks.lit
+++ b/lit/docs/tasks.lit
@@ -3,23 +3,23 @@
\use-plugin{concourse-docs}
The smallest configurable unit in a Concourse pipeline is a single task. A task
-can be thought of as a function from \reference{schema.task-config.inputs} to
+can be viewed as a function from \reference{schema.task-config.inputs} to
\reference{schema.task-config.outputs} that can either succeed or fail.
-Going a bit further, ideally tasks are \italic{pure} functions: given the same
-set of inputs, it should either always succeed with the same outputs or always
+More specifically, ideal tasks are \italic{pure} functions: given the same
+set of inputs, they should either always succeed with the same outputs or always
fail. This is entirely up to your script's level of discipline, however. Flaky
-tests or dependencies on the internet are the most common source of impurity.
+tests or dependencies on the internet are the most common sources of impurity.
-Once you have a running Concourse deployment, you can start configuring your
+Once you have a running Concourse deployment, you can begin configuring your
tasks and executing them interactively from your terminal with the
\reference{fly-cli}{Fly} commandline tool.
-Once you've figured out your task's configuration, you can reuse it for a
+After you've finalized your task's configuration, you can reuse it for a
\reference{jobs}{Job} in your \reference{pipelines}{Pipeline}.
-Conventionally a task's configuration is placed in the same repository as the
-code it's testing, possibly under some \code{ci} directory.
+Typically, a task's configuration is placed in the same repository as the
+code it's testing, often under a \code{ci} directory.
A task's configuration specifies the following:
@@ -30,7 +30,7 @@ A task's configuration specifies the following:
Technically any string value is allowed so long as a worker advertises the
same platform, but in practice only \code{linux}, \code{darwin}, and
- \code{windows} are in use.
+ \code{windows} are used.
}
\required-attribute{image_resource}{anonymous_resource}{
@@ -100,7 +100,7 @@ A task's configuration specifies the following:
}
\optional-attribute{inputs}{[input]}{
- The set of artifacts used by task, determining which artifacts will be
+ The set of artifacts used by the task, determining which artifacts will be
available in the current directory when the task runs.
These are satisfied by \reference{get-step}s or
@@ -122,7 +122,7 @@ A task's configuration specifies the following:
Paths are relative to the working directory of the task unless an
absolute path is given. An absolute path is any path that starts with a
forward slash \code{/}. We recommend only using relative paths unless
- you have a strong technical reason to use absolute paths.
+ you have a compelling technical reason to use absolute paths.
Any parent directory references (\code{../}) in the path will be removed.
}
@@ -158,7 +158,7 @@ A task's configuration specifies the following:
Paths are relative to the working directory of the task unless an
absolute path is given. An absolute path is any path that starts with a
forward slash \code{/}. We recommend only using relative paths unless
- you have a strong technical reason to use absolute paths.
+ you have a compelling technical reason to use absolute paths.
Any parent directory references (\code{../}) in the path will be removed.
}
@@ -179,7 +179,7 @@ A task's configuration specifies the following:
should be able to run whether or not the cache is warmed.
Caches are also scoped to a particular task name inside of a pipeline's
- job. As a consequence, if the job name, step name or cache path are
+ job. As a result, if the job name, step name or cache path are
changed, the cache will not be used. This also means that caches do not
exist for one-off builds.
@@ -199,7 +199,7 @@ A task's configuration specifies the following:
Pipelines can override these params by setting
\reference{schema.task.params} on the \reference{task-step}. This is a common
- method of providing credentials to a task.
+ approach for providing credentials to a task.
}
\required-attribute{run}{command}{
@@ -207,8 +207,8 @@ A task's configuration specifies the following:
Note that this is \italic{not} provided as a script blob, but explicit
\code{path} and \code{args} values; this allows \code{fly} to forward
- arguments to the script, and forces your config \code{.yml} to stay fairly
- small.
+ arguments to the script, and keeps your config \code{.yml} relatively
+ concise.
\schema{command}{
\required-attribute{path}{file-path}{
@@ -274,7 +274,7 @@ A task's configuration specifies the following:
Total CPU shares declared: 4
}}}
- If you introduce another container then the number of CPU time per
+ If you introduce another container then the distribution of CPU time per
container changes. CPU shares are relative to each other.
\codeblock{}{{{
Container A: 2 shares - 25% CPU
@@ -430,4 +430,4 @@ A task's configuration specifies the following:
\table-of-contents
\include-section{tasks/running.lit}
-\include-section{tasks/environment.lit}
+\include-section{tasks/environment.lit}
\ No newline at end of file
diff --git a/lit/docs/vars.lit b/lit/docs/vars.lit
index 742198b1..862614d3 100644
--- a/lit/docs/vars.lit
+++ b/lit/docs/vars.lit
@@ -5,13 +5,13 @@
Concourse supports value substitution in YAML configuration by way of
\code{((vars))}.
-Automation entails the use of all kinds of credentials. It's important to keep
+Automation involves the use of many types of credentials. It's important to keep
these values separate from the rest of your configuration by using vars
instead of hardcoding values. This allows your configuration to be placed
-under source control and allows credentials to be tucked safely away into a
+under source control and enables credentials to be stored safely in a
secure credential manager like Vault instead of the Concourse database.
-Aside from credentials, vars may also be used for generic parameterization of
+Beyond credentials, vars may also be used for generic parameterization of
pipeline configuration templates, allowing a single pipeline config file to be
configured multiple times with different parameters
- e.g. \code{((branch_name))}.
@@ -37,7 +37,7 @@ configured multiple times with different parameters
credential. The interpretation of this value depends on the var source
type. For example, with Vault this may be a path like \code{path/to/cred}.
For the Kubernetes secret manager this may just be the name of a secret.
- For credential managers which support path-based lookup, a
+ For credential managers that support path-based lookup, a
\italic{secret-path} without a leading / may be queried relative to a
predefined set of path prefixes. This is how the Vault credential manager
currently works; \code{foo} will be queried under \code{/concourse/(team
@@ -47,8 +47,8 @@ configured multiple times with different parameters
read. If omitted, the credential manager may choose to read a 'default field'
from the fetched credential if the field exists. For example, the Vault
credential manager will return the value of the \code{value} field if
- present. This is useful for simple single-value credentials where typing
- \code{((foo.value))} would feel verbose.
+ present. This is helpful for simple single-value credentials where typing
+ \code{((foo.value))} would feel redundant.
The \italic{secret-path} and \italic{secret-field} may be surrounded by
double quotes \code{"..."} if they contain special characters like \code{.}
@@ -75,10 +75,10 @@ configured multiple times with different parameters
\code{foo: ((bar))}, whatever value \code{((bar))} resolves to will become
the value of the \code{foo} field in the object. This can be a value of any
type and structure: a boolean, a simple string, a multiline credential like a
- certificate, or a complicated data structure like an array of objects.
+ certificate, or a complex data structure like an array of objects.
This differs from text-based substitution in that it's impossible for a value
- to result in broken YAML syntax, and it relieves the template author from
+ to result in broken YAML syntax, and it frees the template author from
having to worry about things like whitespace alignment.
When a \code{((var))} appears adjacent to additional string content, e.g.
diff --git a/lit/index.lit b/lit/index.lit
index 7cdbae7c..c4de3f80 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -4,7 +4,7 @@
\styled{index}
\splash-intro{
- \inline-header{Concourse is an open-source continuous automation platform.}
+ \inline-header{Concourse is an open-source continuous automation system written in Go.}
Centered around the simple mechanics of \reference{resources}{resources},
\reference{tasks}{tasks}, and \reference{jobs}{jobs}, Concourse delivers a