From 4d30ea40eca04434bef48d5508ced2429fe85c72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Tue, 2 Dec 2025 15:59:12 +0100 Subject: [PATCH 1/3] add naming convention for flows and trails --- .../implementation_guide/phase_2/_index.md | 5 + .../plan_organizational_structure/_index.md | 6 + .../naming_conventions.md | 199 ++++++++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 docs.kosli.com/content/implementation_guide/phase_2/_index.md create mode 100644 docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/_index.md create mode 100644 docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md diff --git a/docs.kosli.com/content/implementation_guide/phase_2/_index.md b/docs.kosli.com/content/implementation_guide/phase_2/_index.md new file mode 100644 index 000000000..7eee494a3 --- /dev/null +++ b/docs.kosli.com/content/implementation_guide/phase_2/_index.md @@ -0,0 +1,5 @@ +--- +title: "Phase 2: Configure Kosli" +bookCollapseSection: true +weight: 200 +--- \ No newline at end of file diff --git a/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/_index.md b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/_index.md new file mode 100644 index 000000000..730997241 --- /dev/null +++ b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/_index.md @@ -0,0 +1,6 @@ +--- +title: "Plan Organizational Structure" +bookCollapseSection: true +weight: 100 +--- + diff --git a/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md new file mode 100644 index 000000000..fc9f754d5 --- /dev/null +++ b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md @@ -0,0 +1,199 @@ +--- +title: "Naming Conventions" +bookCollapseSection: false +weight: 200 +--- + +# Naming Conventions + +Clear and consistent naming makes it easy for everyone to understand what each item in Kosli represents. Good names help you route attestations correctly and quickly find what you need. + +Use these conventions for: +- **Flows** and **Trails** +- **Attestation Types** +- **Environments** + +## General Guidelines + +The general guidelines should be considered best practices for all naming conventions in Kosli. You can adapt them to fit your organization’s needs, but consistency is key. + +All of our proposed conventions follow these general guidelines: + +**Structure**: `` `` `` ``...`` + + +1. **Choose Delimiter**: Choose a delimiter that works for your and stick with it consistently.
+For example hyphen `-`, underscore `_`, tilde `~` or dot `.`.
+Avoid mixing delimiters within the same naming scheme. +2. **Choose case style for elements**: Chose a meaningful case style across elements (e.g., PascalCase, camelCase, snake_case) and use it consistently. Avoid spaces and clashes with delimiters. +3. **Keep it concise**: Shorter names are easier to read and remember. Aim for concise but descriptive names. +4. **Avoid special characters**: Stick to alphanumeric characters and underscores/hyphens + +{{% hint warning %}} +Be aware of using underscore `_` as the delimiter, as that conflicts with snake_case for elements. +{{% /hint %}} + +{{% hint info %}} +The rest of this document uses hyphen `-` as the delimiter in examples, but you can choose any delimiter that fits your needs. +{{% /hint %}} + +### Regular Expression + +To help enforce these conventions programmatically, here are sample regular expressions you can use based on your chosen case style. + +Adjust the regex if you choose a different delimiter. + +{{< tabs "naming-regex" >}} +{{< tab "snake_case" >}} + +**Example**: `element_one`-`element_two`-`element_three` + +```bash +^[a-z][a-z0-9_]*(-[a-z][a-z0-9_]*)*$ +``` + +{{< /tab >}} +{{< tab "camelCase" >}} + +**Example**: `elementOne`-`elementTwo`-`elementThree` + +```bash +^[a-z][a-zA-Z0-9]*(-[a-z][a-zA-Z0-9]*)*$ +``` + +{{< /tab >}} +{{< tab "PascalCase" >}} + +**Example**: `ElementOne`-`ElementTwo`-`ElementThree` + +```bash +^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$ +``` +{{< /tab >}} +{{< /tabs >}} + + +{{% hint info %}} +If you want a specific length limit (e.g., max 50 characters), you can add a lookahead at the start of the regex: + +```bash +^(?=.{1,50}$) # + rest of the regex +``` + +You can use online regex testers like [regex101](https://regex101.com/) to validate and test these expressions. + +{{% /hint %}} + +## Flows + +A clear naming convention transforms a simple ID into a meaningful identifier that everyone understands. This shared language ensures attestations go to the right place and you can track your releases from start to finish. + +### Build Flows + +Build Flows represent how code changes move from commit to artifact. Use the following convention to name Build Flows: + +**Name Convention:** `org`-`repo`-`[service]` + +- **org**: Your organization, division, or team name +- **repo**: Your repository name +- **service (Optional)**: The specific service or component that the artifact belongs to + +{{% hint info %}} +You can skip `service` if your repository produces only one artifact, i.e. non-monorepo setups. +{{% /hint %}} + +{{< tabs "build-flow-examples" >}} +{{< tab "snake_case" >}} + +**Examples:** +- `acme_corp-web_app` (single artifact) +- `acme_corp-web_app-frontend` (with service: frontend) +- `devops_team-mobile_app-backend` (with service: backend) + +```bash +^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*(-[a-z][a-z0-9_]*)?$ +``` + +{{< /tab >}} +{{< tab "camelCase" >}} + +**Examples:** +- `acmeCorp-webApp` (single artifact) +- `acmeCorp-webApp-frontend` (with service: frontend) +- `devopsTeam-mobileApp-backend` (with service: backend) + +```bash +^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*(-[a-z][a-zA-Z0-9]*)?$ +``` +{{< /tab >}} +{{< tab "PascalCase" >}} + +**Examples:** +- `AcmeCorp-WebApp` (single artifact) +- `AcmeCorp-WebApp-Frontend` (with service: frontend) +- `DevOpsTeam-MobileApp-Backend` (with service: backend) + +```bash +^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)?$ +``` +{{< /tab >}} +{{< /tabs >}} + +### Release Flows + +Release Flows represent how artifacts move from build to deployment. Use the following convention to name Release Flows: + +**Name Convention:** `org`-`repo` + +- **Org**: Your organization or team name +- **Repo**: Your repository name + +{{< tabs "release-flow-examples" >}} +{{< tab "snake_case" >}} +**Examples:** +- `acme_corp-web_app` +- `devops_team-mobile_app` +```bash +^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*$ +``` +{{< /tab >}} +{{< tab "camelCase" >}} +**Examples:** +- `acmeCorp-webApp` +- `devopsTeam-mobileApp` +```bash +^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*$ +``` +{{< /tab >}} +{{< tab "PascalCase" >}} +**Examples:** +- `AcmeCorp-WebApp` +- `DevOpsTeam-MobileApp` +```bash +^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*$ +``` +{{< /tab >}} +{{< /tabs >}} + + +## Trails + +### Trails associated with [Build Flows]({{< ref "#build-flows" >}}) + +**Name Convention:** `sha` + +- **sha**: The git commit HEAD SHA that triggered the build. + +### Trails associated with [Release Flows]({{< ref "#release-flows" >}}) +**Name Convention:** `env`-`pr-number` + +- **env**: The target deployment environment (e.g., staging, production) +- **pr-number**: The pull request or change request number associated with the deployment. + +**Examples:** +- `staging-42` +- `production-108` + +```bash +^[a-z][a-z0-9_]*-[0-9]+$ +``` From 8e131bc8dda4b6d9b636d4b451e84f83534881f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 3 Dec 2025 11:45:53 +0100 Subject: [PATCH 2/3] avoid confussion with org as Kosli org --- .../naming_conventions.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md index fc9f754d5..0f17a869c 100644 --- a/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md +++ b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md @@ -92,9 +92,9 @@ A clear naming convention transforms a simple ID into a meaningful identifier th Build Flows represent how code changes move from commit to artifact. Use the following convention to name Build Flows: -**Name Convention:** `org`-`repo`-`[service]` +**Name Convention:** `org-unit`-`repo`-`[service]` -- **org**: Your organization, division, or team name +- **org-unit**: Your organizational unit, division or team name - **repo**: Your repository name - **service (Optional)**: The specific service or component that the artifact belongs to @@ -106,8 +106,8 @@ You can skip `service` if your repository produces only one artifact, i.e. non-m {{< tab "snake_case" >}} **Examples:** -- `acme_corp-web_app` (single artifact) -- `acme_corp-web_app-frontend` (with service: frontend) +- `investment-web_app` (single artifact) +- `investment-web_app-frontend` (with service: frontend) - `devops_team-mobile_app-backend` (with service: backend) ```bash @@ -118,8 +118,8 @@ You can skip `service` if your repository produces only one artifact, i.e. non-m {{< tab "camelCase" >}} **Examples:** -- `acmeCorp-webApp` (single artifact) -- `acmeCorp-webApp-frontend` (with service: frontend) +- `investment-webApp` (single artifact) +- `investment-webApp-frontend` (with service: frontend) - `devopsTeam-mobileApp-backend` (with service: backend) ```bash @@ -129,8 +129,8 @@ You can skip `service` if your repository produces only one artifact, i.e. non-m {{< tab "PascalCase" >}} **Examples:** -- `AcmeCorp-WebApp` (single artifact) -- `AcmeCorp-WebApp-Frontend` (with service: frontend) +- `Investment-WebApp` (single artifact) +- `Investment-WebApp-Frontend` (with service: frontend) - `DevOpsTeam-MobileApp-Backend` (with service: backend) ```bash @@ -143,15 +143,15 @@ You can skip `service` if your repository produces only one artifact, i.e. non-m Release Flows represent how artifacts move from build to deployment. Use the following convention to name Release Flows: -**Name Convention:** `org`-`repo` +**Name Convention:** `org-unit`-`repo` -- **Org**: Your organization or team name -- **Repo**: Your repository name +- **org-unit**: Your organizational unit, division or team name +- **repo**: Your repository name {{< tabs "release-flow-examples" >}} {{< tab "snake_case" >}} **Examples:** -- `acme_corp-web_app` +- `investment-web_app` - `devops_team-mobile_app` ```bash ^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*$ @@ -159,7 +159,7 @@ Release Flows represent how artifacts move from build to deployment. Use the fol {{< /tab >}} {{< tab "camelCase" >}} **Examples:** -- `acmeCorp-webApp` +- `investment-webApp` - `devopsTeam-mobileApp` ```bash ^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*$ @@ -167,7 +167,7 @@ Release Flows represent how artifacts move from build to deployment. Use the fol {{< /tab >}} {{< tab "PascalCase" >}} **Examples:** -- `AcmeCorp-WebApp` +- `Investment-WebApp` - `DevOpsTeam-MobileApp` ```bash ^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*$ From 30de94c340c20e654d680537a7e0517eabe00521 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 3 Dec 2025 12:02:54 +0100 Subject: [PATCH 3/3] fix typo --- .../phase_2/plan_organizational_structure/naming_conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md index 0f17a869c..e7b256374 100644 --- a/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md +++ b/docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md @@ -25,7 +25,7 @@ All of our proposed conventions follow these general guidelines: 1. **Choose Delimiter**: Choose a delimiter that works for your and stick with it consistently.
For example hyphen `-`, underscore `_`, tilde `~` or dot `.`.
Avoid mixing delimiters within the same naming scheme. -2. **Choose case style for elements**: Chose a meaningful case style across elements (e.g., PascalCase, camelCase, snake_case) and use it consistently. Avoid spaces and clashes with delimiters. +2. **Choose case style for elements**: Choose a meaningful case style across elements (e.g., PascalCase, camelCase, snake_case) and use it consistently. Avoid spaces and clashes with delimiters. 3. **Keep it concise**: Shorter names are easier to read and remember. Aim for concise but descriptive names. 4. **Avoid special characters**: Stick to alphanumeric characters and underscores/hyphens