github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/CONTRIBUTING.md (about)

     1  # How to Contribute
     2  
     3  We'd love to accept your patches and contributions to this project. To learn more about the project structure and organization, please refer to Project [Governance](governance.md) information. There are
     4  just a few small guidelines you need to follow.
     5  
     6  ## Contributor License Agreement
     7  
     8  Contributions to this project must be accompanied by a Contributor License
     9  Agreement. You (or your employer) retain the copyright to your contribution;
    10  this simply gives us permission to use and redistribute your contributions as
    11  part of the project. Head over to <https://cla.developers.google.com/> to see
    12  your current agreements on file or to sign a new one.
    13  
    14  You generally only need to submit a CLA once, so if you've already submitted one
    15  (even if it was for a different project), you probably don't need to do it
    16  again.
    17  
    18  ## Contributing large features
    19  
    20  Larger features and all the features that affect the interface (CLI or API) of
    21  kpt components need to have a reviewed and merged design document.  It is OK to
    22  start with a prototype in your private fork but if you intend for your feature
    23  to be shipped in kpt please create a design document with this
    24  [design template](/docs/design-docs/00-template.md).
    25  
    26  You should create a copy of the template and submit a PR for comments and 
    27  review by maintainers.  Once the PR is merged the design is considered approved.
    28  The actual code change PRs should link to the design documents, even though it
    29  is well understood that the design can drift during implementation.
    30  
    31  ## Code reviews
    32  
    33  All submissions, including submissions by project members, require review. We
    34  use GitHub pull requests for this purpose. Consult [GitHub Help] for more
    35  information on using pull requests.
    36  
    37  ## Community Guidelines
    38  
    39  This project follows [Google's Open Source Community Guidelines] and a [Code of
    40  Conduct].
    41  
    42  ## Community Discussion Groups
    43  
    44  Join following groups/channels to discuss ideas with other kpt contributors.
    45  
    46  1. For developers join our [email list](https://groups.google.com/forum/?oldui=1#!forum/kpt-dev)
    47  1. You can add this Google [calendar](https://calendar.google.com/calendar/u/0?cid=Y183cWI2ZTY5MW4zMmhxdmxncTdyMWhmOTFta0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t) to get access to all our meetings. If you'd like to be automatically added to all meetings please join this [list](https://groups.google.com/forum/?oldui=1#!forum/kpt-contribx). Note, our meetings are open to anyone and you do not need an agenda to come. You may be asked for an introduction. For your first meeting, we would suggest you either start with Office Hours or the SIG meeting.
    48  1. Join our [Slack channel](https://kubernetes.slack.com/channels/kpt)
    49  
    50  ## Style Guides
    51  
    52  Contributions are required to follow these style guides:
    53  
    54  - [Error Message Style Guide]
    55  - [Documentation Style Guide]
    56  
    57  ## Contributing to `kpt`
    58  
    59  The kpt toolchain has several components such as `kpt CLI`, `package orchestrator`,
    60  `function catalog`, `function SDKs`, `Backstage UI plugin` and `config sync`. Each
    61  component has their own development process.
    62  Refer to the pointers below to learn more:
    63  
    64  ## Attend Meetings
    65  * All [SIGs](governance.md) have a regular scheduled meeting for feature/roadmap management and planning. For example if you are interested in discussing the roadmap for Config Sync you should attend the **Kpt SIG Config Sync** meeting
    66  * Sub-projects are focused on more tactical items and other sub-project lifecycle items. Sub-projects generally have standups associated with them.
    67  * Working Groups are nimble. Focused a lot on experimentation. Attend if you'd like to see demos and discuss future looking user experiences.
    68  * We regularly have an office hours where we invite the entire community to attend.
    69  * Meeting notes will be kept for all meetings.
    70  * We will not record meetings unless someone explictly asks for one and there are no objections by attendees. If a meeting is recorded a link to it will be left in the notes.
    71  
    72  ### Meeting Notes
    73  Links to meeting notes. Some may require access to mailing lists above. If in doubt join [kpt-contribx](https://groups.google.com/forum/?oldui=1#!forum/kpt-contribx)
    74  
    75  * [Kpt Office Hours](https://docs.google.com/document/d/1I5CJDk9xkDj1vvvwvZNgvaNusE2TanX0Iiy9G1oitz0/view)
    76  * [App Wow Working Group](https://docs.google.com/document/d/1pHsmYjHr9XMwJ_fdJtPiodd8WSg5ilCLIrP_8KE-yKE/view)
    77  
    78  Coming soon
    79  * SIG Config as Data
    80  * SIG Config Sync
    81  
    82  ### kpt CLI
    83  
    84  #### Building the Source
    85  
    86  1. Clone the project
    87  
    88     ```shell
    89     git clone https://github.com/GoogleContainerTools/kpt
    90     cd kpt
    91     ```
    92  
    93  2. Build `kpt` to `$(go env GOPATH)/bin/kpt`
    94  
    95     ```shell
    96     make
    97     ```
    98  
    99  3. Run test
   100  
   101     ```shell
   102     make all
   103     ```
   104  
   105  ### Package Orchestrator
   106  
   107  Package orchestrator code live under `porch` directory in this repo. Please see the
   108  [developer docs for porch](porch/docs/development.md) to learn more.
   109  
   110  ### Function Catalog
   111  
   112  Function catalog has its own repository. Refer to the
   113  [documentation in the kpt-functions-catalog](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/CONTRIBUTING.md)
   114  repo.
   115  
   116  ### Config Sync
   117  
   118  Config Sync has its own [repository](https://github.com/GoogleContainerTools/kpt-config-sync).
   119  Refer to the [documentation in the config-sync repo](https://github.com/GoogleContainerTools/kpt-config-sync/blob/main/docs/contributing.md).
   120  
   121  ### Documentation
   122  
   123  If you are updating the documentation, please do it in separate PRs from code
   124  changes and PR description should start with `Docs:`.
   125  
   126  #### Run the docs locally
   127  
   128  Make docs changes and test them by running the site in a docker container with
   129  `make site-run-server`.
   130  
   131  It's usually a good idea to test locally for the following:
   132  
   133  - Broken links
   134  - Rendering static content
   135  
   136  #### Update docs
   137  
   138  Docs are under [site/] and use [docsify] to present the source markdown files.
   139  The sidebar is automatically updated for the site at deployment time.
   140  
   141  #### Docs Hygiene
   142  
   143  The kpt website uses markdownlint to lint docs for formatting and style. Use
   144  prettier with the `"prettier.proseWrap": "always"` setting to auto-format docs
   145  in VSCode.
   146  
   147  This includes:
   148  
   149  - Lint docs with markdownlint to standardize them and make them easier to
   150    update.
   151  - Run the kpt website through the [W3 Link Checker] in recursive mode and fix
   152    warnings and errors.
   153  
   154  [error message style guide]: docs/style-guides/errors.md
   155  [documentation style guide]: docs/style-guides/docs.md
   156  [github help]: https://help.github.com/articles/about-pull-requests/
   157  [google's open source community guidelines]:
   158    https://opensource.google.com/conduct/
   159  [code of conduct]: CODE_OF_CONDUCT.md
   160  [docsify]: https://docsify.js.org/
   161  [site/]: site/
   162  [w3 link checker]: https://validator.w3.org/checklink/