Naming

Naming allows people to converse unambiguously about the system they are building for the customer.

Some names are important. Others are ephemeral and should have good metaphors. The names themselves are not important, only that they are consistent and consistently applied.

If the correct, intuitive name is not obvious and agreed with little discussion, then using arbitrary names avoids the enormous cost of consensus. There needs to be at least one person who is totally rigid about naming, such that everything remains consistent.

Repository Naming#

Background#

Using meaningful repository names for components makes being Agile difficult because invariably you can only use a name once; when there is a requirement to create a new - or new version - of a component which does the same thing, it is always given the second best name e.g. even if you’re using versions calling a component ‘integration-service-v2’ isn’t preferable to calling it ‘integration-service’.

That means that over time your software will get less meaningful and be harder to understand

To prevent this hereditary degradation whilst still providing a useable name for conversations we adopt naming using good metaphors. These allow for meaningful unambiguous conversations by those that are part of the ‘build’ community but which are entirely interchangeable.

The Metaphor#

Rocks seems like a good source of metaphors for software groups at Practiv

Conversations about [delivery], [staging] and [production] amongst the infrastructure and build teams are able to be concise and well understood by all involved.

Glossary of Terms#

Examples#

There are new clusters being built, and it might seem the obvious thing to do is call them staging and production. Staging and Production are classifications rather than names.

Obviously a new production cluster is not all of production, as you have existing systems providing consumer and internal facing interaction with an expectation of high availability.

What that means is we need names that are useful, but not in of themselves classifying.

In that respect consider practiv-shared-build and [production] as names for Kubernetes clusters that will support support Build and Production workloads respectively.

Example Naming Schedule#

Artifact Naming Conventions#

Proposed naming conventions for artifacts, such that there is no ambiguity and confusion. It empowers developers to make the correct decision for themselves and their team.

Groups#

• forge - The RUN Platform repositories group
• anvil - The Build Platform repositories group
• practiv-shared-build - A repositories group for a cluster that contains Build workloads
• [delivery] - A repositories group for a cluster that contains Delivery workloads
• [production] - A repositories group for a cluster that contains Production workloads

Groups can have their own repositories in GitHub Enterprise, this is useful for tooling that acts on the project monorepo.

See the full table of [Groups]

Application Naming#

<group>-<domain>-<type>

Applications are deployable and releasing them results in something that can run.

type is one of

• backend
• services
• frontend

Examples#

anvil-jenkins

Library Artifact Naming#

<group>-domain-method

Artifacts are jars that collect classes that do one thing

domain is something meaningful to describe the collection of classes

method is one of

• domain (i.e the domain model)
• testutils (collections for shared utilities)
• api
• or the method of implementation of an api

Examples#

• [service]-api - The contract for an application api
• [service]-ebean - The implementation of the contract based on ebean
• [service]-fake - A canned set of responses to the api

Micro service and Micro frontend Artifact Naming#

<group>-domain-vX-method

where the domain is something meaningful

vX is the version that is included in package structure

method is api or the method of implementation

Examples#

• [service]-v1-api - A contract for a webservice
• [service]-v1-jersey - The implementation of the webservice based on jersey
• [service]-v1-springmvc - The implementation of the webservice based on springmvc

Environment naming#

A representative list of environment names

Forge#

These repositories create a docker image that defines a namespace in a cluster. These include the cluster system images and application environments.

• forge-build
• forge-forge-[delivery]
• forge-acceptance
• forge-live

A namespace becomes an environment when a domain is attached to it, e.g.

• forge-[delivery].forge.practiv.io
• acceptance.forge.practiv.io
• live.forge.practiv.io

Product naming#

These repositories create application groups that are always deployed together in a namespace, this is used to promote groups of applications as a unit or “Product”

• forge-[product] - The collection of applications that make up the product

Kubernetes Cluster naming#

Practiv shared build#

These repositories create docker images that automate the creation of a Build cluster, this provides the tooling to build software

• practiv-shared-build-cluster - Repository to produce a Docker image that can build the practiv-shared-build
• practiv-shared-build-run-platform - Repository to produce a Docker image that will manager the environments deployed on the practiv-shared-build cluster

[delivery]#

These repositories create docker images that automate the creation of a Delivery cluster, this provides the RUN platform to deploy and validate software

• [delivery]-cluster - Repository to produce a Docker image that can build the practiv-shared-build
• [delivery]-run-platform - Repository to produce a Docker image that will manage the environments deployed on the practiv-shared-build cluster

[production]#

These repositories create docker images that automate the creation of a Production cluster, this provides the RUN platform to provide services to customers

• [production]-cluster - Repository to produce a Docker image that can build the [production]
• [production]-run-platform - Repository to produce a Docker image that will manage the environments deployed on the [production] cluster

NOTE this is a production cluster, which is defined by a cluster that runs supported application workloads available to consumers. There can be many such clusters and they will change over time, that is why they have arbitrary names.

GCP Project Naming#

Project Name#

These can be sensible and meaningful, I would suggest scoping so it’s obvious where ownership/responsibility lies

We propose that all the practiv projects are prefixed with practiv-

Project Id#

As these don’t change and we want to move projects around for billing, or arbitrary reasons they should be fairly generic.

We propose

practiv-<random 5 digit hash>

Ultimately the project id is NOT meaningful, honestly Google should not allow you to make a field seem meaningful and not allow you to change it. Using a 6 digit number makes it easily recognizable while still unique

GCP Projects Names#

Project ID’s cannot be changed once you make a project

GKE Kubernetes Cluster Names#

A table of proposed GKE cluster names and the projects that belong to.