github.com/crossplane/upjet@v1.3.0/CONTRIBUTING.md (about)

     1  <!--
     2  SPDX-FileCopyrightText: 2023 The Crossplane Authors <https://crossplane.io>
     3  
     4  SPDX-License-Identifier: CC-BY-4.0
     5  -->
     6  
     7  # Contributing to Upjet
     8  
     9  Welcome, and thank you for considering contributing to Upjet. We encourage
    10  you to help out by raising issues, improving documentation, fixing bugs, or
    11  adding new features
    12  
    13  If you're interested in contributing please start by reading this document. If
    14  you have any questions at all, or don't know where to start, please reach out to
    15  us on [Slack]. Please also take a look at our [code of conduct], which details
    16  how contributors are expected to conduct themselves.
    17  
    18  ## Contributing Code
    19  
    20  To contribute bug fixes or features to Upjet:
    21  
    22  1. Communicate your intent.
    23  1. Make your changes.
    24  1. Test your changes.
    25  1. Update documentation and examples where appropriate.
    26  1. Open a Pull Request (PR).
    27  
    28  Communicating your intent lets the Upjet maintainers know that you intend
    29  to contribute, and how. This sets you up for success - you can avoid duplicating
    30  an effort that may already be underway, adding a feature that may be rejected,
    31  or heading down a path that you would be steered away from at review time. The
    32  best way to communicate your intent is via a detailed GitHub issue. Take a look
    33  first to see if there's already an issue relating to the thing you'd like to
    34  contribute. If there isn't, please raise a new one! Let us know what you'd like
    35  to work on, and why. The Upjet maintainers can't always triage new issues
    36  immediately, but we encourage you to bring them to our attention via [Slack].
    37  
    38  Be sure to practice [good git commit hygiene] as you make your changes. All but
    39  the smallest changes should be broken up into a few commits that tell a story.
    40  Use your git commits to provide context for the folks who will review PR, and
    41  the folks who will be spelunking the codebase in the months and years to come.
    42  Ensure each of your commits is signed-off in compliance with the [Developer
    43  Certificate of Origin] by using `git commit -s` and follow the CLA instructions.
    44  The Upjet project highly values readable, idiomatic Go code. Familiarise
    45  yourself with the [Coding Style] and try to preempt any comments your reviewers
    46  would otherwise leave. Run `make reviewable` to lint your change.
    47  
    48  All Upjet code must be covered by tests. Upjet does not use Ginkgo tests and
    49  will request changes to any PR that uses Ginkgo or any third party testing
    50  library, per the common Go [test review comments]. Upjet encourages the use
    51  of table driven unit tests.
    52  
    53  Note that when opening a PR your reviewer will expect you to detail how you've
    54  tested your work. For all but the smallest changes some manual testing is
    55  encouraged in addition to unit tests.
    56  
    57  All Upjet documentation is under revision control; see the [docs] directory
    58  of this repository. Any change that introduces new behaviour or changes existing
    59  behaviour must include updates to any relevant documentation. Please keep
    60  documentation changes in distinct commits.
    61  
    62  Once your change is written, tested, and documented the final step is to have it
    63  reviewed! You'll be presented with a template and a small checklist when you
    64  open a PR. Please read the template and fill out the checklist. Please make all
    65  requested changes in subsequent commits. This allows your reviewers to see what
    66  has changed as you address their comments. Be mindful of  your commit history as
    67  you do this - avoid commit messages like "Address review feedback" if possible.
    68  If doing so is difficult a good alternative is to rewrite your commit history to
    69  clean them up after your PR is approved but before it is merged.
    70  
    71  In summary, please:
    72  
    73  * Discuss your change in a GitHub issue before you start.
    74  * Use your Git commit messages to communicate your intent to your reviewers.
    75  * Sign-off on all Git commits by running `git commit -s`
    76  * Add or update tests for all changes.
    77  * Preempt [Coding Style] review comments.
    78  * Update all relevant documentation.
    79  * Don't force push to address review feedback. Your commits should tell a story.
    80  * If necessary, tidy up your git commit history once your PR is approved.
    81  
    82  Thank you for reading through our contributing guide! We appreciate you taking
    83  the time to ensure your contributions are high quality and easy for our
    84  community to review and accept. Please don't hesitate to [reach out to
    85  us][Slack] if you have any questions about contributing!
    86  
    87  ## Establishing a Development Environment
    88  
    89  Upjet is a set of Go packages that is imported by providers. When you make a
    90  change in Upjet, the best way to test it is to use a `replace` statement in the
    91  `go.mod` file of the provider to use your local version as shown below.
    92  
    93  ```
    94  replace github.com/crossplane/upjet => ../upjet
    95  ```
    96  
    97  Once you complete your change, make sure to run `make reviewable` before opening
    98  your PR.
    99  
   100  In most cases, it's helpful to open the PR in your provider repositories to
   101  show the usage and impact of your change and refer it in your Upjet PR
   102  description. In order for this to work, you'll need to `replace` the Upjet used
   103  in your provider to point to a certain commit in your branch of the provider that
   104  you opened a PR for.
   105  
   106  ```
   107  replace github.com/crossplane/upjet => github.com/<your user name>/upjet <hash of the last commit from your branch>
   108  ```
   109  
   110  [Slack]: https://crossplane.slack.com/archives/C01TRKD4623
   111  [code of conduct]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
   112  [good git commit hygiene]: https://www.futurelearn.com/info/blog/telling-stories-with-your-git-history
   113  [Developer Certificate of Origin]: https://github.com/apps/dco
   114  [test review comments]: https://github.com/golang/go/wiki/TestComments
   115  [docs]: docs/
   116  [Coding Style]: https://github.com/crossplane/crossplane/blob/master/CONTRIBUTING.md#coding-style