Contributing Guidelines

Thank you for considering contributing to Vela. Please read through these contributing guidelines.

Vela project overview

Types of project repos

Core Repos

• types
• server
• sdk-go
• worker
• cli
• ui

Core Repos Dependency Tree

Vela is written in a modular format which creates a dependency tree. The ui is independent.

     ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
     │            │   │            │   │            │   │            │   │            │
     │            │   │            │   │            │   │            │   │            │
 ────┤   types    ├──►│   server   ├──►│   sdk-go   ├──►│   worker   ├──►│    cli     │
     │            │   │            │   │            │   │            │   │            │
     │            │   │            │   │            │   │            │   │            │
     └────────────┘   └────────────┘   └────────────┘   └────────────┘   └────────────┘


     ┌────────────────────────────────────────────────────────────────────────────────┐
     │                                                                                │
     │                                                                                │
 ────┤                                    ui                                          │
     │                                                                                │
     │                                                                                │
     └────────────────────────────────────────────────────────────────────────────────┘

Plugin Repos

• Most repos that start with vela- are plugin repos. They might have a dependency on a core repo. Check out the corresponding go.mod file to confirm.

Supporting Repos

• docs
• vela-tutorials
• community (migrations, proposals, releases (release notes), issues)
• homebrew (brew tap go-vela/vela)

Types of Contributions

Issues

Issues include:

• Bugs
  • Implementation of a feature request or enhancement causing an unexpected result
  • Example: Action performed by an API call is incorrect
• Enhancements
  • A tweak to an existing feature, not resulting in underlying functionality change
  • Examples: Updating log output to be more useful
• Feature requests
  • Net-new functionality
  • Example: Adding an API endpoint

Proposals

Proposals are used to foster discussion around large or breaking feature requests, or when looking for feedback on varied implementation options. Check that an issue or proposal doesn’t exist already.

Create a pull request using the proposal template.

Anyone is welcome to weigh in on a proposal. If you’d like, link it in the public #vela Slack channel for more visibility.

There isn’t a clearly defined proposal process yet (we’re working on that). We do monitor and engage on proposals to reach a consensus. If the proposal is approved to move forward, as indicated within the comments of the proposal pull request, the next step is to create a Feature Request for tracking purposes.

Lifecycle of a Contribution

Determining appropriateness for Vela

Before contributing any code, make sure an issue exists, be sure to checkout current issues and proposals to make sure your idea isn’t already being worked on. We’re working on a public roadmap view to link here.

If an issue does not exist, make sure to create one.

Vela is Target’s primary CI system. We will evaluate issues and proposals, and compare them against our roadmap, what is best for Target, and what makes sense to implement for other customers that will provide a general positive value for other users.

Project boards

Our project boards give you a detailed overview of what’s currently planned or being worked on. Each sprint reflects the stage in our roadmap we are focused on.

Once your proposal or issue is approved, make sure your progress is being tracked in the current sprint.

Categories / Labels

Issues are sorted by using labels and categories (columns) in our backlog. This is to aid us in prioritization and planning.

Some common labels might be:

• Bug
• Enhancement
• Feature

Occasionally, we will use other labels to try and group similar bugs/features/enhancements into a common goal. For example, there might be a label, observability, that could contain bugs/features/enhancements that all pertain to observability.

Backlog Grooming

The Vela core team reviews issues in the community repo once a month. At this point we will determine whether issues fit into our roadmap, assess priority, and potentially close issues that will not be worked by the core team.

Development Workflow

Checkout the README.md in the repo you intend to contribute to, for instructions on how to setup your repo locally and start contributing.

See style guide for guides on implementation.

• Open a pull request!

  • For the title of the pull request, please use the following format:

    feat(wobble): add hat wobble
    ^--^^------^  ^------------^
    |   |         |
    |   |         +---> Summary in present tense.
    |   +---> Scope: a noun describing a section of the codebase (optional)
    +---> Type: chore, docs, feat, fix, refactor, or test.
    

    • feat: adds a new feature (equivalent to a MINOR in Semantic Versioning)
    • fix: fixes a bug (equivalent to a PATCH in Semantic Versioning)
    • docs: changes to the documentation
    • refactor: refactors production code, eg. renaming a variable; doesn’t change public API
    • test: adds missing tests, refactors tests; no production code change
    • chore: updates something without impacting the user (ex: bump a dependency in package.json or go.mod); no production code change

  • If a code change introduces a breaking change, place ! suffix after type, ie. feat(change)!: adds breaking change. correlates with MAJOR in semantic versioning.

  • If your code crosses dependent repos, link associated PRs in PR body.

• PR review process

  • Getting Reviewed: The admins and trusted committers actively watch for incoming PR’s.

  • Getting Approved: For core repos, PRs need 2 approvals. At least one approval must come from an admin, the other can be from a trusted committer. For plugin repos, 1 approval from an admin or trusted committer is needed.

  • Getting Merged: Once approved, your PR will be merged by an admin. If your story crosses dependent repos, PRs will be merged in the appropriate order neccessary.

Releases

Vela is working to release on a consistent schedule. Our current goal is to release a new version once a month so users can work with the latest implemented features and bug fixes. Because Vela is in major version 0, breaking changes may happen on minor version releases. Once we release with major version > 0, semantic versioning will be followed. Currently, main releases only apply to core repos. Plugin repos get version cuts on an as needed basis.

• Patches: Patches will be released on an as needed basis for bug and security fixes. We increment the minor version.
• RC’s (pre-releases): Prior to releasing a main version, we will have at least a week of rc releases for testing purposes.
  • Once an RC is cut:
    • No new features will be included.
    • Enhancements will be considered on a case-by-case basis by admins.
    • Bugs and security fixes can be included.
    • Non-breaking dependency updates can be included.
• Release Notes: You can find a list of release notes in the community repository.

Style Guide

As you contribute to Vela, we ask that you follow these style guides to keep the code clean and consistent.

• Git commit messages: Ensure your commits follow our standards.

• Linters: We use golangci-lint to lint our code. Make sure to run the provided style checks (make fmt, make tidy, etc.) against your code. Please address linter warnings appropriately. If you are intentionally violating a rule that triggers a linter, please annotate the respective code with nolint declarations docs. We are using the following format for nolint declarations:

  //nolint:<linter(s)> // <short reason>
  

  Example:

  //nolint:gocyclo // legacy function is complex, needs simplification
  func superComplexFunction() error {
    // ..
  }
  

  Check the documentation for more examples.

• Documentation: If your contribution warrants documentation within our doc site, have a documentation PR ready and referenced in your code PR. Additionally, when contributing in a plugin repo, make sure to update the plugin’s documentation (DOCS.md) to reflect the change.

• Testing: Make sure you add tests for the code you contribute. The total test coverage should never go down. Checkout the tests in the repo to get started. See cypress, elm, and golang testing frameworks for more details.

• Folder structure: Currently, we use a modified version of the golang project folder structure. When contributing to any repo, keep the structure consistent within the repo. When creating new plugins, be sure to mirror the structure of other plugins (vela-).

• Dependency management: Check out the core repos and the go.mod file in a plugin repo to see how they are dependent on one another. We ask that you use standard libraries whenever possible. See golang modules and npm for dependency management.

• Environment variables: Add environment variables whenever implementation can vary by customer installation, or can be modified outside of a release.

• Commenting: Make sure to add comments to your code when necessary. Users should know what your code is doing by your comments. Check out comments in existing code to get a feel of what and how to comment.

• Accessibility Vela strives to conform to Web Content Accessibility Guidelines 2.1 AA standards for accessibility. Please ensure your contribution(s) meets or exceeds this standard.

Roles

Because Vela is an open source tool, anyone can contribute! We have our admins and trusted committers defined in teams.

• Admins: As admins of go-vela, members of this team work daily to keep Vela up and running. PRs will always need at least one admin approval.
• Trusted committers: This is a group of trusted individuals that are responsible for ushering our contributors into the world of Vela.
• You: Someone who wants to help make Vela the best CI tool out there!

Questions and Contact

If you have a question about contributing to Vela, the above guidelines, or Vela in general, please reach out to the Vela team!

• #vela Slack channel
• Email us at vela@target.com
• Support resources
• Open an issue