Clearly define nomenclature and terms used in the system

[skluck]

Resources

• Source Code

  Uncompiled code pulled directly from VCS repository.

• Build

  Build artifact or dist. This is the source code after build or compilation commands have been run.

• Environment

  A datacenter tier. Typically, application code is promoted and tested in multiple environments before it reaches production.

• Group

  A host server, region or other container for an application to be deployed to.

  Groups have a type (rsync, generic, elastic beanstalk, s3, etc) Groups have a name (server hostname, region, etc)

  Example: Group "CodeDeploy" for "us-east-1". Targets with specific CD details can be attached to this Group.

• Target

  A location or service configuration to deploy a build to. A target consists of a group and additional details. An application can deploy to multiple targets on a host (multiple directories on a server, multiple apps in an AWS region, etc).

  Targets have parameters for the group they belong to (e.g. codedeploy app name and deployment config for CodeDeploy groups)

• Release

  Resource representing a deployment action. No release artifact is stored, this is entirely metadata about the deployment process.

Actions

• Deploy

  Deployment must never be used in documentation or UI. Deploy is an action.

  Example: "Can you generate a build so it can be deployed later tonight at the scheduled time?"

Conflicting concepts

Build is a resource, not an action or verb.

• correct!

  • Generate a build
  • Create build
  • Run build
  • Deploy this build to the test environment.
  • Build is in process
  • Build is running

• wrong!

  • Build a build
  • Build the application
  • The application is building

Deploy is an action, not a resource.

• correct!

  • Deploy a release
  • Deploy this release to the test environment.
  • Deploy release
  • Release is deploying

• wrong!

  • Create a deployment
  • Run deployment process
  • Push the deploy
  • Deployment is running

Do not use

• Push

• Deployment

  Deployment is a term used to describe the overall system, but is not used within the system. E.g. "Deployment system". "Hal handles deployments for my application"

[skluck]

This also affects #8 as the new entity names will align with these terms.

[skluck]

Builds and Releases are both Jobs.

Jobs have

• JobEvent
• JobMeta (data that can be published by a build/release)
• JobProcess (Another action that can be triggered by a job)
  • Currently only used to auto create a release and deploy after a successful build

---

Servers are now Groups. Not thrilled about the naming. Other options: Space, System, Set, Domain, Workspace, Group, Node

A group is created to handle a type of target.

Group for "AWS CodeDeploy" on "us-east-1".

Targets are added to a group for a specific application.

Application B has a Target in Environment C for Group D.

This Target has specific details needed to deploy the release such as S3 Bucket, CodeDeploy App Name, Elastic Beanstalk environment ID, etc.

Targets also keep track of the active release so we know what is currently deployed.

[skluck]

@Nilithus @Robinsonc92 Take a look if these make sense. Open to suggestions on these terms.

[skluck]

I think we're good for now.

See https://github.com/hal-platform/hal-core