github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/CONTRIBUTING.md (about)

     1  # Contributing to Jackal
     2  
     3  First off, thanks so much for wanting to help out! :tada:
     4  
     5  This document describes the steps and requirements for contributing a bug fix or feature in a Pull Request to Jackal!  If you have any questions about the process or the pull request you are working on feel free to reach out in the [Jackal Dev Kubernetes Slack Channel](https://kubernetes.slack.com/archives/C03BP9Z3CMA).
     6  
     7  ## Developer Experience
     8  
     9  Continuous Delivery is core to our development philosophy. Check out [https://minimumcd.org](https://minimumcd.org/) for a good baseline agreement on what that means.
    10  
    11  Specifically:
    12  
    13  - We do trunk-based development (`main`) with short-lived feature branches that originate from the trunk, get merged into the trunk, and are deleted after the merge
    14  - We don't merge code into `main` that isn't releasable
    15  - We perform automated testing on all changes before they get merged to `main`
    16  - We create immutable release artifacts
    17  
    18  ### Developer Workflow
    19  
    20  :key: == Required by automation
    21  
    22  1. Look at the next due [release milestone](https://github.com/Racer159/jackal/milestones) and pick an issue that you want to work on. If you don't see anything that interests you, create an issue and assign it to yourself.
    23  1. Drop a comment in the issue to let everyone know you're working on it and submit a Draft PR (step 4) as soon as you are able. If you have any questions as you work through the code, reach out in the [Jackal Dev Kubernetes Slack Channel](https://kubernetes.slack.com/archives/C03BP9Z3CMA).
    24  1. :key: Set up your Git config to GPG sign all commits. [Here's some documentation on how to set it up](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). You won't be able to merge your PR if you have any unverified commits.
    25  1. Create a Draft Pull Request as soon as you can, even if it is just 5 minutes after you started working on it. We lean towards working in the open as much as we can. If you're not sure what to put in the PR description, just put a link to the issue you're working on.
    26  
    27     - :key: We follow the [conventional commits spec](https://www.conventionalcommits.org/en/v1.0.0/) with the [commitlint conventional config](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) as extended types for PR titles.
    28  
    29  1. :key: Automated tests will begin based on the paths you have edited in your Pull Request.
    30     > ⚠️ **NOTE:** _If you are an external third-party contributor, the pipelines won't run until a [CODEOWNER](https://github.com/Racer159/jackal/blob/main/CODEOWNERS) approves the pipeline run._
    31  1. :key: Be sure to use the [needs-adr,needs-docs,needs-tests](https://github.com/Racer159/jackal/labels?q=needs) labels as appropriate for the PR. Once you have addressed all of the needs, remove the label.
    32  1. Once the review is complete and approved, a core member of the jackal project will merge your PR. If you are an external third-party contributor, two core members of the jackal project will be required to approve the PR.
    33  1. Close the issue if it is fully resolved by your PR. _Hint: You can add "Fixes #XX" to the PR description to automatically close an issue when the PR is merged._
    34  
    35  ## Testing
    36  
    37  This section dives deeper into how we test Jackal
    38  
    39  ### (Optional) Pre-Commit Hooks and Linting
    40  
    41  In this repo you can optionally use [pre-commit](https://pre-commit.com/) hooks for automated validation and linting, but if not CI will run these checks for you.
    42  
    43  ### Code Testing
    44  
    45  Our E2E tests can be found in the `/test` folder and follow the journey of someone as they would use the Jackal CLI. In CI these tests run against our currently supported cluster distros and are the primary way that Jackal code is tested.
    46  
    47  Our Unit tests can be found as `*_test.go` files inside the package that they are designed to test. These are also run in CI and are designed to test small functions with clear interfaces that would be difficult to test otherwise. As a general rule, we are limiting unit tests to the `src/pkg/*` folder.
    48  
    49  All of our tests should be able to be run locally or in CI.
    50  You can learn more about the testing of Jackal [here](docs/12-contribute-to-jackal/2-testing.md).
    51  
    52  ## Documentation
    53  
    54  ### Updating Our Documentation
    55  
    56  Our documentation is auto-generated from the `src/types` and `src/cmd` go packages.  This includes the [Jackal package jsonschema](https://github.com/Racer159/jackal/blob/main/jackal.schema.json), the [Jackal schema docs](https://docs.jackal.dev/docs/create-a-jackal-package/jackal-schema), and the [Jackal CLI docs](https://docs.jackal.dev/docs/the-jackal-cli/).   When an update to types or the CLI commands is made you will need to run `make docs-and-schema` locally to regenerate the schema and documentation. CI checks if this was ran, and will fail if it wasn't.
    57  
    58  We do this so that there is a git commit signature from a person on the commit for better traceability, rather than a non-person entity (e.g. GitHub CI token).
    59  
    60  ### Architecture Decision Records (ADR)
    61  
    62  We've chosen to use ADRs to document architecturally significant decisions. We primarily use the guidance found in [this article by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) with a couple of tweaks:
    63  
    64  - The criteria for when an ADR is needed is undefined. The team will decide when the team needs an ADR.
    65  - We will use the tool [adr-tools](https://github.com/npryce/adr-tools) to make it easier on us to create and maintain ADRs.
    66  - We will keep ADRs in the repository under `adr/NNNN-name-of-adr.md`. `adr-tools` is configured with a dotfile to automatically use this directory and format.
    67  
    68  ### How to use `adr-tools`
    69  
    70  ```bash
    71  # Create a new ADR titled "Use Bisquick for all waffle making"
    72  adr new Use Bisquick for all waffle making
    73  
    74  # Create a new ADR that supersedes a previous one. Let's say, for example, that the previous ADR about Bisquick was ADR number 9.
    75  adr new -s 9 Use scratch ingredients for all waffle making
    76  
    77  # Create a new ADR that amends a previous one. Let's say the previous one was ADR number 15
    78  adr new -l "15:Amends:Amended by" Use store-bought butter for all waffle making
    79  
    80  # Get full help docs. There are all sorts of other helpful commands that help manage the decision log.
    81  adr help
    82  ```