Spinnaker – Code

Docs: Releasing A Patch

Mon, 01 Jan 0001 00:00:00 +0000

Say you’ve written a patch, and it’s been merged into Spinnaker. First off, thanks for helping the project! Odds are, you want to deploy this patch to the Spinnaker you manage. You have a few options available:

Wait for the non-patch release

Any time we release a new minor version of Spinnaker (e.g. 1.16.0 or 1.17.0), we include all commits merged into main for each service. We do this on a quarterly basis by default.

Release branch patch criteria

In order to be considered safe to merge into a release branch, your patch must:

Fix a documented regression in a supported version of Spinnaker . This means that the currently broken functionality must have worked as expected in a previous version of Spinnaker. If the regression is not already documented in a GitHub issue, please create one. Describe the difference between the expected and observed behavior, and include links to the commit that introduced the regression. Indicate to which releases you would like your fix to be backported.
Include tests validating the regression and the fix. The first commit of your patch pull request should add test coverage that demonstrates the existence of the bug and exercises all code paths potentially impacted by your fix. Subsequent commits should fix the bug and update the tests you just added. If your fix is so complex as to make complete tests coverage impossible, it is not a good candidate for merging into a release branch.

These criteria do not apply to security vulnerability patches, which may be merged into release branches at the discretion of the Security SIG and release manager.

Merge into the release branch

If your patch meets the cherry-pick criteria , you can request that your patch be merged into a release branch. Every minor release of Spinnaker has its own release branch. For example, all Spinnaker 2026.0.x releases (2026.0.1, 2026.0.2, etc.) are built from the release-2026.0.x release branch. To get your patch into 2026.0.x, it must be cherry-picked onto that release branch.

After you’ve created a pull request for a fix that you want backported to a release branch, add a comment that includes the following:

@spinnakerbot add-label backport-candidate

Release managers will audit all PRs with the backport-candidate label weekly. Please make sure your pull request description makes it easy for the release manager to evaluate whether your patch meets the release branch patch criteria.

Navigate to GitHub, and create a PR as you would normally, but make sure that your “base” is set to the release branch in the upstream repository as shown below:

{% include figure image_path="./patch.png" %}

Once this PR is merged, your patch should be released in the next few days.

Docs: Code Languages, Libraries, and Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Spinnaker is a collection of microservices built from a common foundation which has evolved over time. You do not need to know all of the technologies listed to contribute. Please consider these standards and conventions when submitting pull requests to Spinnaker.

Languages

Spinnaker is comprised of JVM backend-services and a frontend application (Deck). See an overview of the architecture in our reference documentation.

Use the following languages to fix and extend Spinnaker services:

Deck
- TypeScript
Backend Services
- Java + Lombok
- Kotlin

Sub-projects of Spinnaker microservices are called modules.

Our language of choice is plain java. Groovy in the project is deprecated and no new groovy code will be accepted. Kotlin is acceptable in most areas of the project.

NOTE: There are cross-compilation issues with mixing Groovy and Kotlin in the same source tree. Adding kotlin to a module without removing all groovy references first will not be accepted.

Java

If you are writing new code for an existing module that uses Groovy, please write in Java.

Spinnaker uses Java 17, and where appropriate, we encourage use of newer features such as lambdas, the streams API, the java.time package, and default interface methods.

Groovy

Although much of Spinnaker still has groovy code, we have deprecated Groovy . Please avoid contributing new production code that uses Groovy. Changes to existing Groovy code are acceptable, but new classes should not be written in Groovy.

You are welcome to use Groovy with Spock for writing tests.

Refactoring is also welcome. If your changes touch Groovy code that you can transform into Java, please feel free to do so. Interfaces, for example require almost no changes.

Types from the Groovy runtime libraries should not be exposed in the API of any class. Since Groovy closures can be automatically type-coerced to Java SAM types , please use an appropriate SAM type for parameters or return types that may be implemented with Groovy closures.

Libraries

Current Third-party Libraries

Spinnaker is built on the shoulders of giants. This is not an exhaustive list of libraries that we use, but the ones we’ve identified as having a large presence across the product.

Deck
- React
Backend Services
- Runtime
  - gRPC
  - Jackson
  - Jedis
  - jOOQ
  - Keiko
  - Micrometer
  - OkHttp
  - Spring Boot 3
  - Resilience4j
  - Retrofit2 : Where HTTP is required, converging on Spring RestTemplate .
- Testing
  - Mockk
  - Spock
  - Strikt
  - Testcontainers

Deprecated Third-party Libraries

Spinnaker is an ever-evolving system, and as such, so are the foundations we’ve chosen to build on top of. These libraries still see extensive use within Spinnaker, however they have been deprecated in favor of another solution and the spread of their use is discouraged.

Deck
- Angular : Actively migrating to React.
Backend Services
- Hystrix : Replaced by Resilience4j.
- Spectator : Replaced by Micrometer.
- Spek : Converging on Strikt + Mockk.

Conventions

Code formatting

We follow Google’s Java Style Guide for Java. We follow ktlint for Kotlin.

For Groovy and miscellaneous files, please use:

2 space indents.
No more than 1 consecutive line of whitespace.
Line breaks rather than overly long lines (limit to 120 column width if possible).
Camel case conventions as per Java.

Code formatting is applied automatically with a git pre-commit hook, but if you need to check or apply code formatting outside of this process:

Format code: ./gradlew spotlessApply
Check code: ./gradlew spotlessCheck

Package structure

Spinnaker microservices automatically component-scan for @Configuration classes in the com.netflix.spinnaker.config package. Other classes should be placed in com.netflix.spinnaker.<service>.<feature> where <service> is the microservice name, for example orca or clouddriver and <feature> is something descriptive of the feature being implemented.

Please do not separate classes into different packages according to what they are. Packages should represent the group of classes that implement a particular piece of functionality not all components of a particular type.

Naming things

Please use descriptive but concise names for variables, classes, properties, methods, and so on. Longer names are good when they add clarity. Shorter names are good when they reduce redundancy.

Representing units

It’s preferable to use types that properly represent things like durations, or timestamps (java.time.Duration and java.time.Instant would be ideal in those specific cases). If that’s not practical please include a suffix on the property / variable name that describes the unit. A property declared as public long getTimeout() is ambiguous and can easily lead to errors when developers using your code assume what the units are.

For example, these names are much less likely to result in errors:

public long getTimeoutMillis();

public long getTimeoutSeconds();

Nullability

When writing Java code, please use @jakarta.annotation.Nullable and @jakarta.annotation.Nonnull annotations on return types and parameters of public methods. This lets the Kotlin compiler make better decisions about the interactions between Kotlin and Java code.

Date and time values

Please use classes from java.time and not java.util.Date or java.util.Calendar.

Exceptions

Please select, or create, appropriate exception types rather than throwing overly general things such as RuntimeException.

Exception types you create should extend RuntimeException (directly or indirectly). Please try to include descriptive information in exception messages, especially for errors that will be surfaced to the user.

The package kork-exceptions includes some standard base exception types that you are encouraged to use directly or extend as needed.

Deprecations

Deprecating old, unused or high-debt code is highly encouraged! When deprecating code, you MUST include the @Deprecation annotation, along with supporting documentation:

Why is this code deprecated? This should be a link to a Github Issue with the no-lifecycle label.
What is this code being replaced by?

Do not annotate code as deprecated without additional context. Deprecations without sufficient context will be rejected.

Ambiguous Types

Refrain from using open-ended, ambiguous types, such as Map<String, Object>. These types, while flexible, make APIs unobvious, difficult to integrate with and test. Instead, use well-defined types, or if a Map type is truly needed, use the most constrictive contract as possible, such as Map<String, String>.

Testing

We really appreciate contributions that include tests. Thorough testing at the unit level with maybe an integration test to validate how components tie together is ideal.

Testing tools

Spinnaker uses Spock for testing Java and Groovy code.

For Kotlin we are still pinning down specific best practices but currently recommend JUnit tests (written in Kotlin) using AssertJ and Mockito via mockito-kotlin .

Docs: Developer How Tos

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Managing Deprecations

Mon, 01 Jan 0001 00:00:00 +0000

Before you begin

The best way to propose a deprecation is to first open an issue , ping the #dev channel in Slack, and discuss your deprecation before taking action.

Often times, you will need the following information:

An overview of what the functionality does or intended to do.
A description of why this functionality should be deprecated and, eventually, removed.
A description of the replacement functionality, if any, or information about why this functionality will not need a replacement.
The scope of impact on the codebase: What services will be affected?
How will users migrate off this functionality?¹

Deprecation approval

Before a deprecation cycle starts, it must be approved by either the SIG owning the functionality, or by the Technical Oversight Committee. This approval is noted by labeling the issue as “approved” or “rejected”, depending on the decision.

Deprecation cycles

A deprecation must be announced at least 1 release cycle in advance of when the functionality will be removed; however, a less aggressive window should generally be used. Deprecation announcements should be added to the Next Release Preview page with a link to the relevant GitHub issue as well as links to any other supporting documentation, such as configuration or migration docs.

Once the Spinnaker version with the deprecation announcement gets released, you are encouraged to remove the deprecated code from the codebase as soon as possible. This gives you and others sufficient time to fix edge cases that may arise from the removal before the next Spinnaker release.

Automated migrations are not always possible. In lieu of a migration, documentation must be provided on how to migrate installations. ↩︎

Docs: Pull Requests and Changes

Mon, 01 Jan 0001 00:00:00 +0000

Change Process

Once you’ve implemented a bug fix or feature, it’s time to submit a pull request to Spinnaker. We recommend small, well-tested pull requests as a starting point for new technical contributors. For information on the correct fork-and-PR GitHub workflows to follow when contributing, reference the local clone guide.

To work on bigger technical changes, follow the feature proposal or RFC processes.

Pull Request Tips

Check that your title describes your changes and adheres to our message conventions .
Add inline code comments to changes that might not be obvious.
Squash your commits into logically reviewable chunks when you first submit your PR. Address feedback in follow-up (unsquashed) commits. It’s much easier to review incremental changes to feedback when the commits are kept separate.
All pull requests should get reviewed by at least one other member of the Spinnaker organization before merging. (While some members of the organization have access to merge without a review, this should only be done in an emergency or when merging a large series of dependency bumps across repositories.)
Squash your commits when merging to the branch.

Commit and PR message conventions

Please follow conventions below in your git commit messages. Since GitHub auto-fills Pull Request titles from the first commit message of the PR, following these conventions should help to title your PRs according to our community standards.

Note: In order to track and summarize the changes happening in Spinnaker, we use a changelog automation tool called clog which scrapes information from commit messages, which follow the ‘conventional’ format.

To summarize, messages should be formatted as follows:

<type>(<scope>): <subject>
<empty line>
<body>
<empty line>
<footer>

Type

Type	Purpose
feat	A new feature. Please also link to the issue (in the body) if applicable. Causes a minor version bump.
fix	A bug fix. Please also link to the issue (in the body) if applicable.
docs	A documentation change.
style	A code change that does not affect the meaning of the code, (e.g. indentation).
refactor	A code change that neither fixes a bug or add a feature.
perf	A code change that improves performance.
test	Adding missing tests.
chore	Changes to build process or auxiliary tools or libraries such as documentation generation.
config	Changes to configurations that have tangible effects on users, (e.g. renaming properties, changing defaults, etc).

The type of keyword affects the next semantic version bump. The feat keyword causes a minor version bump, while the rest of the keywords cause a patch version bump. Major version bumps are triggered by the presence of the words BREAKING CHANGE in the commit message body. This is covered more in Body .

If you don’t use one of the previous types (or don’t follow the convention), your commit will not be included in the generated changelog. Your change will still affect the next semantic version bump, but it will be considered a patch change, not a major or minor change (even if the change is a breaking change or a feature).

If you submit a pull request with multiple commits and choose to Squash and Merge the pull request, the individual commit message are not added to the changelog, only the pull request message is. To include each commit in your pull request in the changelog and next version calculation, merge the changes without squashing.

Scope

The scope of the commit message indicates the area or feature of Spinnaker the commit applies to. For instance, if you were to submit a patch to the Google provider in Clouddriver, your commit message might look something like:

feat(provider/google): Updated forwarding rule schema.

or if you submit a fix pertaining to authentication in Gate:

fix(authN): Fixed session authentication coherence.

The scope is purposefully left open-ended, but try to group similar changes using the same value. Changes that have the same scope will be grouped together during changelog generation:

Features

Some_scope
- First feature goes here.
- Second feature goes here.

Subject

The subject should be a short summary of the patch.

Body

The body should include any detailed information about the patch; however, these can also go in the pull request body.

Any information about breaking changes should be present in the footer. To signify a breaking change, add one line at the end of the commit message with ‘BREAKING CHANGE’ in the line:

feat(provider/google): Added a very important and breaking feature.

BREAKING CHANGE: More detail here if necessary.

At minimum, ‘BREAKING CHANGE’ must be specified on the last line. The extra detail is not mandatory.

Feature Proposals

The Spinnaker community has historically avoided accepting pull requests that add features without prior discussion. If you would like to propose a feature:

Open an issue describing the desired functionality.
Share your issue link in the #dev channel in Slack.
Consider discussing your ideas with other contributors before implementing them, to avoid rework.

Requests For Change

If your change is large or very impactful, we may encourage you to submit an RFC:

Use the RFC template .
Consult several already-submitted RFCs for reference.
When your RFC is ready, add it to the <code>spinnaker/governance/rfc</code> directory with a pull request. Approvers will see and review it.

Spinnaker – Code

Docs: Releasing A Patch

Wait for the non-patch release

Release branch patch criteria

Merge into the release branch

Docs: Code Languages, Libraries, and Conventions

Languages

Java

Groovy

Libraries

Current Third-party Libraries

Deprecated Third-party Libraries

Conventions

Code formatting

Package structure

Naming things

Representing units

Nullability

Date and time values

Exceptions

Deprecations

Ambiguous Types

Testing

Testing tools

Docs: Developer How Tos

Docs: Managing Deprecations

Before you begin

Deprecation approval

Deprecation cycles

Docs: Pull Requests and Changes

Change Process

Pull Request Tips

Commit and PR message conventions

Type

Scope

Subject

Body

Footer

Feature Proposals

Requests For Change