docs: add notes about change detection

Signed-off-by: AtomicFS <vojtech.vesely@9elements.com>

Author: AtomicFS

cmd/firmware-action/recipes/config.go

@@ -166,6 +166,8 @@ func (opts CommonOpts) GetOutputDir() string {
 	return opts.OutputDir
 }
 
+// ANCHOR: CommonOptsGetSources
+
 // GetSources returns slice of paths to all sources which are used for build
 func (opts CommonOpts) GetSources() []string {
 	sources := []string{}
@@ -180,6 +182,8 @@ func (opts CommonOpts) GetSources() []string {
 	return sources
 }
 
+// ANCHOR_END: CommonOptsGetSources
+
 // Config is for storing parsed configuration file
 type Config struct {
 	// defined in coreboot.go

cmd/firmware-action/recipes/coreboot.go

@@ -71,6 +71,8 @@ func (opts CorebootOpts) GetArtifacts() *[]container.Artifacts {
 	return opts.CommonOpts.GetArtifacts()
 }
 
+// ANCHOR: CorebootOptsGetSources
+
 // GetSources returns slice of paths to all sources which are used for build
 func (opts CorebootOpts) GetSources() []string {
 	sources := opts.CommonOpts.GetSources()
@@ -109,6 +111,8 @@ func (opts CorebootOpts) GetSources() []string {
 	return sources
 }
 
+// ANCHOR_END: CorebootOptsGetSources
+
 // ProcessBlobs is used to figure out blobs from provided data
 func (opts CorebootOpts) ProcessBlobs() ([]BlobDef, error) {
 	blobs := []BlobDef{}

docs/src/SUMMARY.md

@@ -23,6 +23,7 @@
         - [Build Docker container on the fly](firmware-action/build_dockerfile_on_the_fly.md)
         - [Interactive debugging](firmware-action/interactive.md)
         - [Offline usage](firmware-action/offline_usage.md)
+        - [Change detection](firmware-action/change_detection.md)
     - [Migration instructions]()
         - [Migration from v0.13.x to v0.14.0](firmware-action/migration/v0.13.x--v0.14.0/migrate.md)
 

docs/src/firmware-action/change_detection.md

@@ -0,0 +1,40 @@
+# Change detection
+
+firmware-action has basic detection of changes.
+
+Related temporary files to aid in change detection are stored in `.firmware-action/` directory, which is always created in current working directory.
+
+```admonish note
+It is save to delete the `.firmware-action/` directory, but keep in mind that change detection depends on its existence.
+
+If `.firmware-action/` directory is deleted, it will be re-created on next firmware-action execution.
+
+It might be advantageous to also include this directory in caches / artifacts when in CI. Preserving these files might reduce run time in the CI.
+```
+
+
+## Sources modification time
+
+When building a module, firmware-action checks recursively all sources for a given module. For all module types, list of sources include repository and all input files.
+
+```admonish example collapsible=true title="Code snippet: Common sources"
+~~~golang
+{{#include ../../../cmd/firmware-action/recipes/config.go:CommonOptsGetSources}}
+~~~
+```
+
+Each module type has then additional source files. For example `coreboot`, where list of sources also includes `defconfig` and all the blobs.
+```admonish example collapsible=true title="Code snippet: Additional coreboot sources"
+~~~golang
+{{#include ../../../cmd/firmware-action/recipes/coreboot.go:CorebootOptsGetSources}}
+~~~
+```
+
+When a module is successfully built, a file containing time stamp is saved to `.firmware-action/timestamps/` directory.
+
+On next run, this file (if exists) is loaded with time stamp of last successful run. Then all sources are recursively checked for any file that was modified since the last successful run. If no file was modified since the loaded time stamp, module is considered up-to-date and build is skipped. If any of the files has newer modified time, module is re-built.
+
+
+## Configuration file changes
+
+Firmware-action can also detect changes in the configuration file. For each module, on each successful build, it stores a copy of the configuration in `.firmware-action/configs/` directory. On next run, current configuration is compared to configuration of last successful build, and if they differ, module is re-built.

docs/src/firmware-action/features.md

@@ -5,4 +5,5 @@
 - [Interactive mode](./interactive.md)
 - [Offline usage](./offline_usage.md)
 - [Recursive builds](./config.md#modules)
+- [Change detection](./change_detection.md)