architect-orb

This repository hosts the source code for giantswarm/architect orb.

Jobs

Jobs available in this orb are documented here

Design and Goals

• Replacing architect entirely is not a goal. But replacing most of its functionality is.
• Being explicit. Desire to do actual job. E.g. building a docker image and pushing it to a registry should be explicitly specified in the build.
• Making builds understandable without looking into architect codebase.
• Having one line binary call on each job step - to make the outputs grouped and visible and keeping build configurations sane. Good example is helm-chart-template.
• Using architect executor with the latest architect docker image most of time.
• Using binaries other than architect when appropriate (they should be available inside architect executor most of the time). E.g. docker, git, helm, etc. Instead of wrapping existing well known functionality in architect binary.
• Using architect commands for complex tasks. Good example is architect helm template instead of awkward and error prone sed calls.

Coding Guidelines

• Jobs should be documented in docs.
• Jobs should call only commands and not have steps defined directly. I.e. no run: key in /jobs directory.
• Steps defined in commands should be named. Names should be prefixed with architect/COMMAND_NAME like here. They should have imperative format.
• Steps defined in commands should be small. Ideally single binary call. One exception is step skipping described later.
• Steps should be described using the name: attribute, to make it as easy as possible to understand what's happening.
• Step skipping should be done using when: and unless: steps.
• If using when: and unless: steps is difficult then multiline skipping is acceptable. See this code for example.
• Temporary information between steps should be carried in files prefixed with .build_.
• Temporary .build_* files should be only used in scope of a single command.
• A command using temporary files should clean them with cleanup step in format linked here. This should be the last step of the command.

Development

• For a completely new job that is not reusing any of the existing commands the fastest way to prototype is probably creating an inline orb. Here is an example of working inline orb prototype: https://github.com/giantswarm/release-operator/pull/121/files.
• Create a PR and test your changes using the dev version, by changing the orb declaration to architect: giantswarm/architect@dev:your-branch. Dev versions are mutable and deleted after 90 days. Details here https://circleci.com/docs/2.0/using-orbs/#development-and-production-orbs-versioning-semantics.
• Update Unreleased section of CHANGELOG.md file with the changes introduced in your PR.
• If you want to also make a new release follow the steps in Releases section (which is most likely the case) or merge your PR.

Releases

1. Open a new PR with following changes:
   • Change Unreleased header of CHANGELOG.md to the version you are going to release.
   • Create new Unreleased section in CHANGELOG.md.
   • Update the URLs at the bottom.
2. Merge your PR.
3. Create GitHub release for the commit merged to master branch [here] (https://github.com/giantswarm/architect-orb/releases/new). Fill in only the Tag version fields. The rest should remain empty.