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..e7b256374 --- /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**: 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 + +{{% 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-unit`-`repo`-`[service]` + +- **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 + +{{% 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:** +- `investment-web_app` (single artifact) +- `investment-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:** +- `investment-webApp` (single artifact) +- `investment-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:** +- `Investment-WebApp` (single artifact) +- `Investment-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-unit`-`repo` + +- **org-unit**: Your organizational unit, division or team name +- **repo**: Your repository name + +{{< tabs "release-flow-examples" >}} +{{< tab "snake_case" >}} +**Examples:** +- `investment-web_app` +- `devops_team-mobile_app` +```bash +^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*$ +``` +{{< /tab >}} +{{< tab "camelCase" >}} +**Examples:** +- `investment-webApp` +- `devopsTeam-mobileApp` +```bash +^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*$ +``` +{{< /tab >}} +{{< tab "PascalCase" >}} +**Examples:** +- `Investment-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]+$ +```