Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
142 lines (99 loc) · 7.16 KB

CONTRIBUTING.md

File metadata and controls

142 lines (99 loc) · 7.16 KB
Raw

Contributing Guidelines

Welcome to Shipwright, we are glad you want to contribute to the project! This document contains general guidelines for submitting contributions. Each component of Shipwright will have its own specific guidelines.

Contributing prerequisites (CLA/DCO)

The project enforces Developer Certificate of Origin (DCO). By submitting pull requests submitters acknowledge they grant the Apache License v2 to the code and that they are eligible to grant this license for all commits submitted in their pull requests.

Getting Started

All contributors must abide by our Code of Conduct.

The core code for Shipwright is located in the following repositories:

  • build - the Build APIs and associated controller to run builds.
  • cli - the shp command line for Shipwright builds
  • operator - an operator to install Shipwright components on Kubernetes via OLM.

Technical documentation is spread across the code repositories, and is consolidated in the website repository. Content in website is published to shipwright.io

Creating new Issues

We recommend to open an issue for the following scenarios:

  • Asking for help or questions. (Use the discussion or help_wanted label)
  • Reporting a bug. (Use the kind/bug label)
  • Requesting a new feature. (Use the kind/feature label)

Use the following checklist to determine where you should create an issue:

  • If the issue is related to how a Build or BuildRun behaves, or related to Build strategies, create an issue in build.
  • If the issue is related to the command line, create an issue in cli.
  • If the issue is related to how the operator installs Shipwright on a cluster, create an issue in operator.
  • If the issue is related to the shipwright.io website, create an issue in website.

If you are not sure, create an issue in the community repository, and the Shipwright maintainers will route it to the correct location.

If feature request is sufficiently broad or significant, the community may ask you to submit a SHIP enhancement proposal. Please refer to the SHIP guidelines to learn how to submit a SHIP proposal.

Writing Pull Requests

Contributions can be submitted by creating a pull request on Github. We recommend you do the following to ensure the maintainers can collaborate on your contribution:

  • Fork the project into your personal Github account.

  • Create a new feature branch for your contribution from the latest main branch commit.

  • Make your changes, ensuring that tests are passing.

  • Commit your code changes locally, with a clear commit message and a Developer Certificate of Origin (DCO) sign-off footer. You can do this by using the -s flag when committing changes with git, or amending your commit message after the fact:

    git commit --amend -s

  • Before opening your pull request, squash your commits into a small number of logical, reviewable units (ideally a single commit for small changes). This keeps the project history clean and makes the change easier to review, bisect, and revert if needed. You can squash commits with an interactive rebase against the branch point:

    git fetch upstream # fetch the changes from remote
git rebase -i upstream/main

    Avoid "fixup", "typo", or "address review comments" commits in the final history; fold those changes into the relevant commit before requesting review, or as part of addressing review feedback prior to merge.

  • Write commit messages following the Conventional Commits specification. Each commit message should be structured as:

    <type>[optional scope]: <description>

[optional body]

[optional footer(s)]

    Commonly used types include:

    • feat: a new feature
    • fix: a bug fix
    • docs: documentation only changes
    • test: adding or correcting tests
    • refactor: a code change that neither fixes a bug nor adds a feature
    • chore: changes to tooling, dependencies, or other maintenance tasks

    For example: fix(controller): requeue BuildRun on transient API errors. This convention makes the commit history easier to scan, and helps reviewers understand the intent of a change at a glance.

  • Push your code changes to GitHub, then create a pull request with a clear title for the community review. Most Shipwright repositories use templates to generate pull request descriptions. If so, please fill out all sections so your change is easier to discuss and accept. Finally, please reference the appropriate GitHub issue if your change provides a fix or implements a feature.

NOTE: All commits must have a DCO sign-off in order for your change to be accepted. See more information on DCO signing here.

Code review process

Once your pull request is submitted, a Shipwright maintainer should be assigned to review your changes.

The code review should cover:

  • Ensure all related tests (unit, integration and e2e) are passing.
  • Ensure the code style is compliant with the coding conventions
  • Ensure the code is properly documented, e.g. enough comments where needed.
  • Ensure the code is adding the necessary test cases (unit, integration or e2e) if needed.

Contributors are expected to respond to feedback from reviewers in a constructive manner. Reviewers are expected to respond to new submissions in a timely fashion, with clear language if changes are requested.

Once the pull request is approved and marked "lgtm", it will get merged.

Community Meetings Participation

We run the community meetings every Monday at 13:00 UTC time. For each upcoming meeting we generate a new issue where we layout the topics to discuss. See our previous meetings outcomes. Please request an invite in our Slack channel or join the shipwright-dev mailing list.

All meetings are also published on our public calendar.

Contact Information