docs: update docs with v1.0.0 changes #47

mbshields · 2023-06-16T22:05:17Z

Updates with new CLI command and command options
New article on Dockerfile conversion
What's New additions for v1.0.0
Minor corrections

Signed-off-by: mbshields <[email protected]>

mikemccracken · 2024-01-10T23:24:36Z

docs/reference/stacker_cli.md

@@ -26,11 +29,12 @@
        stacker [global options] command [command options] [arguments...]

        VERSION:
-        stacker v0.40.1-e54a685 liblxc a330126b45c7c3b6fcf0f9ba6c1eda7bdb4e508a
+        stacker v1.0.0-rc4-8e267fc liblxc 727adc05220e9b8b594c5bc2124bef5b2e0abe7a


maybe this should just be <version> and <liblxc commit hash>, since these won't directly match what's in the release?

Your variables do not appear in the comment, but I think you mean this?
stacker <version> liblxc <digest>

yes, sorry!

mikemccracken · 2024-01-10T23:25:48Z

docs/user_guide/template_substitution.md

+
+You can also declare variable substitutions in a separate file which is then included in the build command as in this example:
+
+`stacker build --substitute-file <filename>`


is there an example of the file format somewhere that we could link to here? or just show an example directly here?

Added simple example

great, thanks

mikemccracken · 2024-01-10T23:26:52Z

docs/whats-new.md

+
+### Convert a Dockerfile for stacker
+
+- A new [`stacker convert`](reference/stacker_cli.md#stacker-convert) command performs a conversion of a Dockerfile into a stacker.yaml file. During the conversion, some variables from the Dockerfile may be exported to a substitution file.  


Suggested change

- A new [`stacker convert`](reference/stacker_cli.md#stacker-convert) command performs a conversion of a Dockerfile into a stacker.yaml file. During the conversion, some variables from the Dockerfile may be exported to a substitution file.

- A new [`stacker convert`](reference/stacker_cli.md#stacker-convert) command performs a conversion of a Dockerfile into a stacker.yaml file. During the conversion, some variables from the Dockerfile may be exported to a substitution file to be used with the `--substitution-file` argument.

mikemccracken · 2024-01-10T23:28:08Z

docs/whats-new.md

+
+### Specify a single working directory
+
+- A new [`stacker`](reference/stacker_cli.md#stacker) command option, `work-dir`, sets the working directory for stacker's cache, OCI output, and rootfs output. The existing command options `stacker-dir`, `oci-dir`, and `roots-dir` can then be omitted or used to override the `work-dir` setting.


Suggested change

- A new [`stacker`](reference/stacker_cli.md#stacker) command option, `work-dir`, sets the working directory for stacker's cache, OCI output, and rootfs output. The existing command options `stacker-dir`, `oci-dir`, and `roots-dir` can then be omitted or used to override the `work-dir` setting.

- A new [`stacker`](reference/stacker_cli.md#stacker) command option, `--work-dir`, sets the working directory for stacker's cache, OCI output, and rootfs output. The existing command options `--stacker-dir`, `--oci-dir`, and `--roots-dir` can then be omitted or used to override the `--work-dir` setting.

mikemccracken · 2024-01-10T23:28:53Z

docs/whats-new.md

+
+- A new [`stacker`](reference/stacker_cli.md#stacker) command option, `work-dir`, sets the working directory for stacker's cache, OCI output, and rootfs output. The existing command options `stacker-dir`, `oci-dir`, and `roots-dir` can then be omitted or used to override the `work-dir` setting.
+
+### Import contents when no shell exists


Suggested change

### Import contents when no shell exists

### Import contents when no shell exists in the base image

mikemccracken · 2024-01-10T23:32:56Z

docs/reference/stacker_file.md

-`config` key is a special type of entry in the root in the `stacker.yaml` file.
-It cannot contain a layer definition, it is used to provide configuration
+The `config` key is a special type of entry in the root of the `stacker.yaml` file.
+It cannot contain a layer definition; it is used to provide configuration


Suggested change

It cannot contain a layer definition; it is used to provide configuration

It cannot contain an image definition; it is used to provide configuration

mikemccracken · 2024-01-10T23:33:08Z

docs/reference/stacker_file.md

-`config` key is a special type of entry in the root in the `stacker.yaml` file.
-It cannot contain a layer definition, it is used to provide configuration
+The `config` key is a special type of entry in the root of the `stacker.yaml` file.
+It cannot contain a layer definition; it is used to provide configuration
 applicable for building all the layers defined in this file. For example,


layers -> images

mikemccracken · 2024-01-10T23:33:23Z

docs/reference/stacker_file.md

@@ -221,16 +215,16 @@ applicable for building all the layers defined in this file. For example,

 If the `prerequisites` list is present under the `config` key, stacker will
 make sure to build all the layers in the stacker.yaml files found at the paths


layers ->images

mikemccracken · 2024-01-10T23:34:56Z

docs/whats-new.md

+
+### Publish specific layers
+
+- By default, the [`stacker publish`](reference/stacker_cli.md#stacker-publish) command pushes all layers in a stacker.yaml file instead of only the required layers. Using a new command option, `layer <value>`, you can explicitly specify which layers are to be published.  This command option can be specified multiple times, selecting each layer to be included.


i see that 'layer' is hard coded in the command arg. we should change that and change it here to say "image"

Should I keep "layers" in this paragraph until the code is changed?

sure, that's fine, unless @rchincha has a reason to leave the option as --layer, in which case we'll need to explain it here.

also, when we do change it, let's add the dashes so it reads --layer

When (if?) we change the argument name, should this section become "### Publish specific images"? And should all instances of 'layer' be changed then to 'image'?

mikemccracken · 2024-01-10T23:35:34Z

docs/whats-new.md


-USAGE:
-   stacker build [command options] [arguments...]
+- Prior to v0.40.1, copying content into a layer permanently involved bind mounting a shell such as busybox and invoking appropriate commands using the `run` directive. Now `import` directive [allows](reference/stacker_file.md#import-dest) for the `dest` option to achieve the same.


Suggested change

- Prior to v0.40.1, copying content into a layer permanently involved bind mounting a shell such as busybox and invoking appropriate commands using the `run` directive. Now `import` directive [allows](reference/stacker_file.md#import-dest) for the `dest` option to achieve the same.

- Prior to v0.40.1, copying content into an image permanently involved bind mounting a shell such as busybox and invoking appropriate commands using the `run` directive. Now `import` directive [allows](reference/stacker_file.md#import-dest) for the `dest` option to achieve the same.

Signed-off-by: mbshields <[email protected]>

mikemccracken · 2024-01-11T18:00:10Z

docs/whats-new.md


-USAGE:
-   stacker build [command options] [arguments...]
+- Prior to v0.40.1, copying content into an image permanently involved bind mounting a shell such as busybox and invoking appropriate commands using the `run` directive. Now `import` directive [allows](reference/stacker_file.md#import-dest) for the `dest` option to achieve the same.


I missed this earlier, but this paragraph is only relevant in the context of scratch images. you could always copy into an image without bind mounting a shell if your base image had a shell already.

maybe this should read "prior to v0.40.1, copying content into a scratch image ..."

Signed-off-by: mbshields <[email protected]>

rchincha

lgtm

docs: update docs with v1.0.0 changes

ed3f906

Signed-off-by: mbshields <[email protected]>

mbshields mentioned this pull request Jun 16, 2023

docs: update CLI reference with 1.0.0 changes #46

Closed

docs: update What's New for v1.0.0, add SBOM article

8f2b9d4

Signed-off-by: mbshields <[email protected]>

rchincha requested review from rchamarthy, rchincha and mikemccracken January 10, 2024 22:57

mikemccracken suggested changes Jan 10, 2024

View reviewed changes

docs: resolve more PR comments

6f64e02

Signed-off-by: mbshields <[email protected]>

mikemccracken reviewed Jan 11, 2024

View reviewed changes

docs: resolve comments, change zotregistry.io to .dev

654b948

Signed-off-by: mbshields <[email protected]>

rchincha approved these changes Apr 8, 2024

View reviewed changes

rchincha merged commit affffe8 into project-stacker:main Apr 8, 2024
3 checks passed

mbshields deleted the docs_mishield_v100 branch April 15, 2024 23:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update docs with v1.0.0 changes #47

docs: update docs with v1.0.0 changes #47

mbshields commented Jun 16, 2023

mikemccracken Jan 10, 2024 •

edited

Loading

mbshields Jan 11, 2024 •

edited

Loading

mikemccracken Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 11, 2024

mbshields Jan 11, 2024

mikemccracken Jan 10, 2024

mbshields Jan 11, 2024

mikemccracken Jan 11, 2024

rchincha left a comment


		You can also declare variable substitutions in a separate file which is then included in the build command as in this example:

		`stacker build --substitute-file <filename>`


		### Convert a Dockerfile for stacker

		- A new [`stacker convert`](reference/stacker_cli.md#stacker-convert) command performs a conversion of a Dockerfile into a stacker.yaml file. During the conversion, some variables from the Dockerfile may be exported to a substitution file.


		### Specify a single working directory

		- A new [`stacker`](reference/stacker_cli.md#stacker) command option, `work-dir`, sets the working directory for stacker's cache, OCI output, and rootfs output. The existing command options `stacker-dir`, `oci-dir`, and `roots-dir` can then be omitted or used to override the `work-dir` setting.


		- A new [`stacker`](reference/stacker_cli.md#stacker) command option, `work-dir`, sets the working directory for stacker's cache, OCI output, and rootfs output. The existing command options `stacker-dir`, `oci-dir`, and `roots-dir` can then be omitted or used to override the `work-dir` setting.

		### Import contents when no shell exists

	It cannot contain a layer definition; it is used to provide configuration
	It cannot contain an image definition; it is used to provide configuration

		@@ -221,16 +215,16 @@ applicable for building all the layers defined in this file. For example,

		If the `prerequisites` list is present under the `config` key, stacker will
		make sure to build all the layers in the stacker.yaml files found at the paths


		### Publish specific layers

		- By default, the [`stacker publish`](reference/stacker_cli.md#stacker-publish) command pushes all layers in a stacker.yaml file instead of only the required layers. Using a new command option, `layer <value>`, you can explicitly specify which layers are to be published. This command option can be specified multiple times, selecting each layer to be included.

	- Prior to v0.40.1, copying content into a layer permanently involved bind mounting a shell such as busybox and invoking appropriate commands using the `run` directive. Now `import` directive [allows](reference/stacker_file.md#import-dest) for the `dest` option to achieve the same.
	- Prior to v0.40.1, copying content into an image permanently involved bind mounting a shell such as busybox and invoking appropriate commands using the `run` directive. Now `import` directive [allows](reference/stacker_file.md#import-dest) for the `dest` option to achieve the same.

docs: update docs with v1.0.0 changes #47

docs: update docs with v1.0.0 changes #47

Conversation

mbshields commented Jun 16, 2023

mikemccracken Jan 10, 2024 • edited Loading

Choose a reason for hiding this comment

mbshields Jan 11, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rchincha left a comment

Choose a reason for hiding this comment

mikemccracken Jan 10, 2024 •

edited

Loading

mbshields Jan 11, 2024 •

edited

Loading