docs: Describe versioning in KRCI (#412)

KubeRocketCI · Mar 7, 2025 · 2557ab0 · 2557ab0
1 parent e9e9feb
commit 2557ab0
Show file tree

Hide file tree

Showing 21 changed files with 149 additions and 7 deletions.
diff --git a/docs/assets/user-guide/versioning/codebase_versioning.png b/docs/assets/user-guide/versioning/codebase_versioning.png
diff --git a/docs/assets/user-guide/versioning/codebasebranch_data.png b/docs/assets/user-guide/versioning/codebasebranch_data.png
diff --git a/docs/assets/user-guide/versioning/codebaseimagestream_data.png b/docs/assets/user-guide/versioning/codebaseimagestream_data.png
diff --git a/docs/assets/user-guide/versioning/default_versioning.png b/docs/assets/user-guide/versioning/default_versioning.png
diff --git a/docs/assets/user-guide/versioning/git_tag.png b/docs/assets/user-guide/versioning/git_tag.png
diff --git a/docs/assets/user-guide/versioning/semantic_versioning.png b/docs/assets/user-guide/versioning/semantic_versioning.png
diff --git a/docs/assets/user-guide/versioning/versions_in_pipelines.png b/docs/assets/user-guide/versioning/versions_in_pipelines.png
diff --git a/docs/user-guide/artifact-versioning.md b/docs/user-guide/artifact-versioning.md
@@ -0,0 +1,70 @@
+---
+title: "Artifact Versioning in KubeRocketCI"
+description: "Explanation of artifact versioning types in KubeRocketCI, including default and semantic versioning, and how to customize versioning patterns for codebases."
+sidebar_label: "Artifact Versioning"
+---
+<!-- markdownlint-disable MD025 -->
+
+# Artifact Versioning in KubeRocketCI
+
+<head>
+  <link rel="canonical" href="https://docs.kuberocketci.io/docs/user-guide/artifact-versioning" />
+</head>
+
+This page describes artifact versioning types in KubeRocketCI, outlining their differences and versioning patterns.
+
+Artifact versioning in KubeRocketCI is designed to ensure each build and deployment can be uniquely identified, managed, and traced back to its source.
+
+Artifact versioning is defined for every codebase individually when creating a codebase:
+
+  ![Select codebase versioning](../assets/user-guide/versioning/codebase_versioning.png "Select codebase versioning")
+
+A new application version appears when a build pipeline run completes successfully. A successfully built artifact is marked with the new version once the `git-tag`, `update-cbb`, and `update-cbis` steps complete successfully:
+
+  ![Git-tag step](../assets/user-guide/versioning/codebase_versioning.png "Git-tag step")
+
+Application version can also be seen in the pipeline that built the version:
+
+  ![Versions in pipelines](../assets/user-guide/versioning/versions_in_pipelines.png "Versions in pipelines")
+
+## Versioning Types
+
+KubeRocketCI supports two versioning types: default and semver. They offer different patterns for tagging codebases.
+
+### Default Versioning
+
+Default versioning generates versions based on the branch name and datetime, e.g. (`BRANCH-DATETIME`):
+
+  ![Default versioning](../assets/user-guide/versioning/default_versioning.png "Default versioning")
+
+### Semantic Versioning
+
+Semantic versioning (semver) structures versions as `MAJOR.MINOR.PATCH-BUILD_ID`, based on the [semantic versioning standards](https://semver.org/):
+
+  ![Semantic versioning](../assets/user-guide/versioning/semantic_versioning.png "Semantic versioning")
+
+Several other resources are also involved in managing semantic versioning.
+
+The first resource is **CodebaseBranch**. It contains data major version and build number for a specific branch. Besides, it contains codebase versioning-related data, including:
+
+- **Version History**: A record of all versions generated from the branch.
+- **Build Information**: Details of the current and most recent successful builds, which may include version identifiers.
+
+**CodebaseBranch** data is displayed in the codebase details page:
+
+  ![CodebaseBranch data](../assets/user-guide/versioning/codebasebranch_data.png "CodebaseBranch data")
+
+The second resource is **CodebaseImageStream**. It contains application container versions built for container registry. The available container versions are displayed in the environment details page when deploying an application:
+
+  ![CodebaseImageStream data](../assets/user-guide/versioning/codebaseimagestream_data.png "CodebaseImageStream data")
+
+## Custom Versioning
+
+User can adjust artifact versioning pattern by updating [`get-version`](https://github.com/epam/edp-tekton/tree/master/charts/pipelines-library/templates/tasks/getversion) CI step to address your personal needs.
+
+## Related Articles
+
+* [Add Application](add-application.md)
+* [Add Cluster](add-cluster.md)
+* [Manage GitOps](gitops.md)
+* [Manage Registries](manage-container-registries.md)
diff --git a/docs/user-guide/gitops.md b/docs/user-guide/gitops.md
@@ -1,8 +1,8 @@
 ---
 
-title: "Manage Clusters"
+title: "Manage GitOps"
 description: "Explore the GitOps section in KubeRocketCI for automating infrastructure and application deployments with a Git repository-driven approach."
-sidebar_label: "Manage Clusters"
+sidebar_label: "Manage GitOps"
 
 ---
 <!-- markdownlint-disable MD025 -->

diff --git a/sidebars.ts b/sidebars.ts
@@ -455,6 +455,7 @@ const sidebars: SidebarsConfig = {
               ],
             },
             'user-guide/manage-branches',
+            'user-guide/artifact-versioning',
           ],
         },
         {

diff --git a/versioned_docs/version-3.10/assets/user-guide/versioning/codebase_versioning.png b/versioned_docs/version-3.10/assets/user-guide/versioning/codebase_versioning.png
diff --git a/versioned_docs/version-3.10/assets/user-guide/versioning/codebasebranch_data.png b/versioned_docs/version-3.10/assets/user-guide/versioning/codebasebranch_data.png
diff --git a/...ned_docs/version-3.10/assets/user-guide/versioning/codebaseimagestream_data.png b/...ned_docs/version-3.10/assets/user-guide/versioning/codebaseimagestream_data.png
diff --git a/versioned_docs/version-3.10/assets/user-guide/versioning/default_versioning.png b/versioned_docs/version-3.10/assets/user-guide/versioning/default_versioning.png
diff --git a/versioned_docs/version-3.10/assets/user-guide/versioning/git_tag.png b/versioned_docs/version-3.10/assets/user-guide/versioning/git_tag.png
diff --git a/versioned_docs/version-3.10/assets/user-guide/versioning/semantic_versioning.png b/versioned_docs/version-3.10/assets/user-guide/versioning/semantic_versioning.png
diff --git a/versioned_docs/version-3.10/assets/user-guide/versioning/versions_in_pipelines.png b/versioned_docs/version-3.10/assets/user-guide/versioning/versions_in_pipelines.png
diff --git a/versioned_docs/version-3.10/user-guide/artifact-versioning.md b/versioned_docs/version-3.10/user-guide/artifact-versioning.md
@@ -0,0 +1,70 @@
+---
+title: "Artifact Versioning in KubeRocketCI"
+description: "Explanation of artifact versioning types in KubeRocketCI, including default and semantic versioning, and how to customize versioning patterns for codebases."
+sidebar_label: "Artifact Versioning"
+---
+<!-- markdownlint-disable MD025 -->
+
+# Artifact Versioning in KubeRocketCI
+
+<head>
+  <link rel="canonical" href="https://docs.kuberocketci.io/docs/user-guide/artifact-versioning" />
+</head>
+
+This page describes artifact versioning types in KubeRocketCI, outlining their differences and versioning patterns.
+
+Artifact versioning in KubeRocketCI is designed to ensure each build and deployment can be uniquely identified, managed, and traced back to its source.
+
+Artifact versioning is defined for every codebase individually when creating a codebase:
+
+  ![Select codebase versioning](../assets/user-guide/versioning/codebase_versioning.png "Select codebase versioning")
+
+A new application version appears when a built pipeline run completes successfully. A successfully built artifact is marked with the new version on the `git-tag` step:
+
+  ![Git-tag step](../assets/user-guide/versioning/codebase_versioning.png "Git-tag step")
+
+Application version can also be seen in the pipeline that built the version:
+
+  ![Versions in pipelines](../assets/user-guide/versioning/versions_in_pipelines.png "Versions in pipelines")
+
+## Versioning Types
+
+KubeRocketCI supports two versioning types: default and semver. They offer different patterns for tagging codebases.
+
+### Default Versioning
+
+Default versioning generates versions based on the branch name and datetime, e.g. (`BRANCH-DATETIME`):
+
+  ![Default versioning](../assets/user-guide/versioning/default_versioning.png "Default versioning")
+
+### Semantic Versioning
+
+Semantic versioning (semver) structures versions as `MAJOR.MINOR.PATCH-BUILD_ID`, based on the [semantic versioning standards](https://semver.org/):
+
+  ![Semantic versioning](../assets/user-guide/versioning/semantic_versioning.png "Semantic versioning")
+
+Several other resources are also involved in managing semantic versioning.
+
+The first resource is **CodebaseBranch**. It contains data major version and build number for a specific branch. Besides, it contains codebase versioning-related data, including:
+
+- **Version History**: A record of all versions generated from the branch.
+- **Build Information**: Details of the current and most recent successful builds, which may include version identifiers.
+
+CodebaseBranch data is displayed in the codebase details page:
+
+  ![Semantic versioning](../assets/user-guide/versioning/codebasebranch_data.png "Semantic versioning")
+
+The second resource is **CodebaseImageStream**. It contains application container versions built for container registry. The available container versions are displayed in the environment details page when deploying an application:
+
+  ![Semantic versioning](../assets/user-guide/versioning/codebaseimagestream_data.png "Semantic versioning")
+
+## Custom Versioning
+
+User can adjust artifact versioning pattern by updating [`get-version`](https://github.com/epam/edp-tekton/tree/master/charts/pipelines-library/templates/tasks/getversion) CI step to address your personal needs.
+
+## Related Articles
+
+* [Add Application](add-application.md)
+* [Add Cluster](add-cluster.md)
+* [Manage GitOps](gitops.md)
+* [Manage Registries](manage-container-registries.md)
diff --git a/versioned_docs/version-3.10/user-guide/gitops.md b/versioned_docs/version-3.10/user-guide/gitops.md
@@ -1,8 +1,8 @@
 ---
 
-title: "Manage Clusters"
+title: "Manage GitOps"
 description: "Explore the GitOps section in KubeRocketCI for automating infrastructure and application deployments with a Git repository-driven approach."
-sidebar_label: "Manage Clusters"
+sidebar_label: "Manage GitOps"
 
 ---
 <!-- markdownlint-disable MD025 -->

diff --git a/versioned_docs/version-3.9/user-guide/gitops.md b/versioned_docs/version-3.9/user-guide/gitops.md
@@ -1,8 +1,8 @@
 ---
 
-title: "Manage Clusters"
+title: "Manage GitOps"
 description: "Explore the GitOps section in KubeRocketCI for automating infrastructure and application deployments with a Git repository-driven approach."
-sidebar_label: "Manage Clusters"
+sidebar_label: "Manage GitOps"
 
 ---
 <!-- markdownlint-disable MD025 -->

diff --git a/versioned_sidebars/version-3.10-sidebars.json b/versioned_sidebars/version-3.10-sidebars.json
@@ -428,7 +428,8 @@
                 "user-guide/infrastructure"
               ]
             },
-            "user-guide/manage-branches"
+            "user-guide/manage-branches",
+            "user-guide/artifact-versioning"
           ]
         },
         {
-Original file line number
+Diff line change
@@ Expand Up / @@ -455,6 +455,7 @@ const sidebars: SidebarsConfig = { @@
                   ],
                 },
                 'user-guide/manage-branches',
+                'user-guide/artifact-versioning',
               ],
             },
             {
@@ Expand Down @@