From 644d47655b9134de90d7ca7bf06a648ddd1481df Mon Sep 17 00:00:00 2001 From: mbshields Date: Sat, 31 Dec 2022 16:45:03 -0800 Subject: [PATCH] docs: polish grammar Committing changes on behalf of egrover Signed-off-by: mbshields --- docs/concepts/oci_image_layout.md | 2 +- docs/concepts/stacker_architecture.md | 2 +- docs/developer_guide/CONTRIBUTING.md | 40 ++++++++++++------------ docs/developer_guide/building_stacker.md | 10 +++--- docs/features.md | 2 +- docs/get_started/get_stacker.md | 2 +- docs/get_started/hello_stacker_image.md | 14 ++++----- docs/reference/stacker_file.md | 6 ++-- docs/user_guide/annotation_support.md | 2 +- docs/user_guide/debugging.md | 8 ++--- 10 files changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/concepts/oci_image_layout.md b/docs/concepts/oci_image_layout.md index 51054bc..431247e 100644 --- a/docs/concepts/oci_image_layout.md +++ b/docs/concepts/oci_image_layout.md @@ -7,4 +7,4 @@ format. OCI Image Layout Specification The OCI Image Layout is the directory structure for OCI content-addressable blobs and location-addressable references (refs). - This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync). + This layout MAY be used in a variety of transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync). diff --git a/docs/concepts/stacker_architecture.md b/docs/concepts/stacker_architecture.md index d2fb83f..161e5f3 100644 --- a/docs/concepts/stacker_architecture.md +++ b/docs/concepts/stacker_architecture.md @@ -1,6 +1,6 @@ # Stacker Architecture -The following diagram illustrates the relationship between the various +The diagram below illustrates the relationship between the various directives and the internal state maintained during the image build process. ![architecture](../assets/images/illustrations/arch.jpg) diff --git a/docs/developer_guide/CONTRIBUTING.md b/docs/developer_guide/CONTRIBUTING.md index 84e8f3c..54d600f 100644 --- a/docs/developer_guide/CONTRIBUTING.md +++ b/docs/developer_guide/CONTRIBUTING.md @@ -58,16 +58,16 @@ make ## Contribute Workflow PRs are always welcome, even if they only contain small fixes like typos or a few -lines of code. If there will be a significant effort, please document it as an -issue and get a discussion going before starting to work on it. +lines of code. If there is a significant effort, please document it as an +issue and get a discussion going before working on it. -Please submit a PR broken down into small changes bit by bit. A PR consisting of -a lot features and code changes may be hard to review. It is recommended to -submit PRs in an incremental fashion. +Please submit a PR broken down into small changes, bit by bit. A PR with +a lot features and code changes may be hard to review. It is recommended that +you submit PRs in an incremental fashion. -Note: If you split your pull request to small changes, please make sure any of -the changes goes to master will not break anything. Otherwise, it can not be -merged until this feature complete. +Note: If you split your pull request to small changes, please make sure that +the changes that go to master do not break existing features. Otherwise, it cannot be +merged until this feature is complete. ## Develop, Build and Test @@ -79,24 +79,24 @@ such as this one. As we are enforcing standards set by [golangci-lint](https://github.com/golangci/golangci-lint), please always run a full 'make' on source -code before committing your changes. This will trigger compilation, unit tests +code before committing your changes. This will trigger compilation, unit tests, and linting. If it reports an issue, in general, the preferred action is to fix -the code. We try to enforce the guideline that code coverage doesn't drop as +the code. We try to enforce the guideline that code coverage does not drop as code is added or modified. ## Automated Testing (via CI/CD) -Once your pull request has been opened, stacker will start a full CI pipeline +Once your pull request is opened, stacker will start a full CI pipeline against it that compiles, and runs unit tests and linters. ## Reporting issues -It is a great way to contribute to stacker by reporting an issue. Well-written +A great way to contribute to stacker is by reporting an issue. Well-written and complete bug reports are always welcome! Please open an issue on Github and follow the template to fill in required information. -Before opening any issue, please look up the existing issues to avoid submitting -a duplication. If you find a match, you can "subscribe" to it to get notified on +Before opening any issue, please review existing issues to avoid submitting +a duplicate. If you find a match, you can "subscribe" to it to get notified of updates. If you have additional helpful information about the issue, please leave a comment. @@ -107,13 +107,13 @@ Configuration files of stacker Log files as per configuration. -Because the issues are open to the public, when submitting the log +Because the issues are open to public, when submitting the log and configuration files, be sure to remove any sensitive information, e.g. user name, password, IP address, and company name. You can replace those parts with "REDACTED" or other strings like "****". -Be sure to include the steps to reproduce the problem if applicable. +Be sure to include the steps to reproduce the problem, if applicable. It can help us understand and fix your issue faster. ## Documenting @@ -124,12 +124,12 @@ documentation is as important as the code itself. The main location for the documentation is the website repository. The images referred to in documents can be placed in docs/img in that repo. -Documents are written with Markdown. See Writing on GitHub for more details. +Documents are written using Markdown. See Writing on GitHub for more details. ## Design New Features -You can propose new designs for existing stacker features. You can also design -entirely new features, Please submit a proposal in GitHub issues. stacker +You can propose new designs for existing stacker features. You can also design new features. +Please submit a proposal in GitHub issues. stacker maintainers will review this proposal as soon as possible. This is necessary to -ensure the overall architecture is consistent and to avoid duplicated work in +ensure consistency in the overall architecture and to avoid duplicate effort in the roadmap. diff --git a/docs/developer_guide/building_stacker.md b/docs/developer_guide/building_stacker.md index 9c82410..c3b6779 100644 --- a/docs/developer_guide/building_stacker.md +++ b/docs/developer_guide/building_stacker.md @@ -18,10 +18,10 @@ On Fedora 31 you can install Go with the following command: #### Other Distributions If Go is not already packaged for your Linux distribution, you can get the -latest Go version here: +latest Go version at: https://golang.org/dl/#stable -Go can be installed using the instructions on on the official Go website: +Go can be installed using the instructions on the official Go website at: https://golang.org/doc/install#install ### Other Dependencies @@ -50,7 +50,7 @@ packages: Contrary to what the documentation in squashfs implies, squashtool and libsquash from squash-tools-ng need to be installed globally, as user specific -path overrides aren't propagated into `make check`'s test envs. +path overrides are not propagated to `make check`'s test envs. Thus, when you reach the step **install into mylocal="$HOME/lib"** from the squashfs guide, use the config below. You can put them at the end of your .bashrc file so you don't need to run them every time. @@ -58,11 +58,11 @@ Thus, when you reach the step **install into mylocal="$HOME/lib"** from the squa export LD_LIBRARY_PATH=$mylocal/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} export PKG_CONFIG_PATH=$mylocal/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} -Since the path **/usr/local** is owned by root, when you reach the step to run **make install**, you need to run it as **sudo**. +Because the path **/usr/local** is owned by root, when you reach the step to run **make install**, you need to run it as **sudo**. `make check` requires the **golangci-lint** binary to be present in $GOPATH/bin -Since there are some tests that run with elevated privileges and use git, it will complain that the stacker folder is unsafe as it is owned by your user. To prevent that, we need to tell git to consider that folder as safe. To do this, open your git config file (**.gitconfig**) and add the following line with the path to your local stacker folder. Below is an example: +Because there are a few tests that run with elevated privileges and use git, it will complain that the stacker folder is unsafe as it is owned by your user. To prevent that, we need to tell git to consider that folder as safe. To do this, open your git config file (**.gitconfig**) and add the following line with the path to your local stacker folder. Below is an example: [safe] directory = /home/chofnar/github/stacker diff --git a/docs/features.md b/docs/features.md index 3e91b70..cc763ed 100644 --- a/docs/features.md +++ b/docs/features.md @@ -4,7 +4,7 @@ The key features of `stacker` are: ## Single Binary -One statically built binary for simplified download and install with no +One statically built binary for simplified download and installation with no additional dependencies or services. ## Unprivileged diff --git a/docs/get_started/get_stacker.md b/docs/get_started/get_stacker.md index 1ff7003..d626389 100644 --- a/docs/get_started/get_stacker.md +++ b/docs/get_started/get_stacker.md @@ -35,7 +35,7 @@ stacker check && echo "stacker is ready to use!" ## Overlay filesystem -An underlying overlayfs cannot back stacker becuase the stacker needs to create +An underlying overlayfs cannot back stacker because the stacker needs to create whiteout files, and the kernel (rightfully) forbids manual creation of whiteout files on overlay filesystems. No additional userspace dependencies are required to use the overlayfs backend. diff --git a/docs/get_started/hello_stacker_image.md b/docs/get_started/hello_stacker_image.md index 4e0e3b1..090b056 100644 --- a/docs/get_started/hello_stacker_image.md +++ b/docs/get_started/hello_stacker_image.md @@ -1,7 +1,7 @@ # A "Hello Stacker" Image Stacker builds OCI images using the YAML definition in a file referred to as -the stacker file. So let's create a stacker file definition that packages a +the Stacker file. Let's create a stacker file definition that packages a simple "Hello Stacker!" script into an OCI container image. ```yaml title="Hello Stacker" @@ -20,13 +20,13 @@ hello-stacker: `hello-stacker`, the first key in the above YAML, builds an OCI image named __hello-stacker__. -The `from` section defines that `hello-stacker` image builds on top of an -existing image called `zothub.io/tools/busybox:stable`, and that the base image is of type +The `from` section defines that `hello-stacker` image builds on an +existing image called `zothub.io/tools/busybox:stable`, and the base image is of type `docker` downloaded from URL `docker://zothub.io/tools/busybox:stable`. -The `run` section defines a build script. This script is executed on top of the -ubuntu image's root file system, creates a file called -`/hello-stacker-app/hello.sh`, and makes it executable. +The `run` section defines a build script. This script is executed on the +ubuntu image's root file system and creates an executable file called +`/hello-stacker-app/hello.sh`. `entrypoint` defines that `/hello-stacker-app/hello.sh` is executed as the `init` process on creating this container by a container runtime. @@ -113,7 +113,7 @@ Image config: } ``` -The next thing to note is that if we rebuild the image without any modifications +Note that if we rebuild the image without any modifications to the stacker file, less things happen: ```bash title="stacker caching" diff --git a/docs/reference/stacker_file.md b/docs/reference/stacker_file.md index 1392d2a..b4e8efd 100644 --- a/docs/reference/stacker_file.md +++ b/docs/reference/stacker_file.md @@ -25,7 +25,7 @@ line flags or stacker-config file. STACKER_OCI_DIR config name 'oci_dir', cli flag '--oci-dir' -The stacker build environment will have the following environment variables +The stacker build environment has the following environment variables available for reference: * `STACKER_LAYER_NAME`: the name of the layer being built. `STACKER_LAYER_NAME` @@ -126,7 +126,7 @@ import: ### `overlay_dirs` This directive works only with OverlayFS backend storage. -The `overlay_dirs` directive describes what directories (content) from the host should be +The `overlay_dirs` directive describes the directories (content) from the host that should be available in the container's filesystem. It preserves all file/dirs attributes but no owner or group. @@ -143,7 +143,7 @@ to be available under container's /usr/local/ and all the files/dirs from the ho ### `environment`, `labels`, `working_dir`, `volumes`, `cmd`, `entrypoint`, `user` -These all correspond exactly to the similarly named bits in the [OCI image +These correspond exactly to the similarly named bits in the [OCI image config spec](https://github.com/opencontainers/image-spec/blob/master/config.md#properties), and are available for users to pass things through to the runtime environment diff --git a/docs/user_guide/annotation_support.md b/docs/user_guide/annotation_support.md index 038a5f2..bfc35f7 100644 --- a/docs/user_guide/annotation_support.md +++ b/docs/user_guide/annotation_support.md @@ -1,6 +1,6 @@ # Additing Annotations -In the stacker yaml file, `annotations` is a user-specified key value map that will be included in the +In the stacker yaml file, `annotations` is a user-specified key value map that is included in the final OCI image. Note that these annotations are included in the image manifest itself and not as part of the index.json. diff --git a/docs/user_guide/debugging.md b/docs/user_guide/debugging.md index 8cb4521..ba2c7f5 100644 --- a/docs/user_guide/debugging.md +++ b/docs/user_guide/debugging.md @@ -1,7 +1,7 @@ # Debugging The first step to trying to find a bug in stacker is to run it with --debug. -This will give you a stack trace from where (at least in stacker's code) the +This gives you a stack trace from where (at least in stacker's code) the error originated via [github.com/pkg/errors](https://github.com/pkg/errors). Sometimes it is useful to write a small reproducer in `test/`, and run it with: @@ -12,10 +12,10 @@ make check TEST=myreproducer.bats ## Overlayfs / layer issues -Another thing `--debug` will show you is what overlay arguments it is sending + `--debug` also shows you the overlay arguments it is sending to LXC. Note that the build overlay filesystem never exists in the host mount namespace, but is created by liblxc in the child namespace. Sometimes it can be -useful to take these overlay args and split up the lowerdirs: +useful to take these overlay arguments and split up the lowerdirs: ``` ./stacker/stacker_layers/.roots/sha256_f8e46c301da6347e78057d8fe48a6bbd8fc0cab213d47825f5c0c0646f542b6b/overlay @@ -44,7 +44,7 @@ make LXC_CLONE_URL=https://github.com/tych0/lxc LXC_BRANCH=my-debug-branch Stacker links against this through a convoluted mechanism: it builds a static C program in `/cmd/lxc-wrapper/` that takes a few relevant arguments about what mode to drive liblxc in. Stacker uses the `go-embed` mechanism to embed the -resulting statically linked binary, and then resolves and execs it at runtime +resulting statically linked binary, and then resolves and executes it at runtime via the code in `/embed-exec`. The reason for all this indirection vs. linking against something directly is that the kernel does not allow multithreaded programs to unshare user namespaces. Since the go runtime spawns many threads