sigs.k8s.io/gateway-api@v1.0.0/site-src/contributing/devguide.md (about)

     1  <!--
     2  Copyright 2019 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8       http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  -->
    16  
    17  ## Developing Gateway API
    18  
    19  You must have a working [Go environment] and then clone the repo:
    20  
    21  ```
    22  mkdir -p $GOPATH/src/sigs.k8s.io
    23  cd $GOPATH/src/sigs.k8s.io
    24  git clone https://github.com/kubernetes-sigs/gateway-api
    25  cd gateway-api
    26  ```
    27  
    28  This project works with Go modules; you can chose to setup your environment
    29  outside $GOPATH as well.
    30  
    31  # Building, testing and deploying
    32  
    33  You will need to have Docker installed to perform the steps below.
    34  
    35  ## Project management
    36  
    37  We are using the Github issues and project dashboard to manage the list of TODOs
    38  for this project:
    39  
    40  * [Open issues][gh-issues]
    41  * [Project dashboard][gh-dashboard]
    42  
    43  Issues labeled `good first issue` and `help wanted` are especially good for a
    44  first contribution.
    45  
    46  We use [milestones][gh-milestones] to track our progress towards releases.
    47  These milestones are generally labeled according to the [semver][semver]
    48  release version tag that they represent, meaning that in general we only focus
    49  on the next release in the sequence until it is closed and the release is
    50  finished. Only Gateway API maintainers are able to create and attach issues to
    51  milestones.
    52  
    53  We use [priority labels][prio-labels] to help indicate the timing importance of
    54  resolving an issue, or whether an issue needs more support from its creator or
    55  the community to be prioritized. These labels can be set with the [/priority
    56  command in PR and issue comments][issue-cmds]. For example,
    57  `/priority important-soon`.
    58  
    59  [gh-issues]: https://github.com/kubernetes-sigs/gateway-api/issues
    60  [gh-dashboard]: https://github.com/kubernetes-sigs/gateway-api/projects/1
    61  [gh-milestones]: https://github.com/kubernetes-sigs/gateway-api/milestones
    62  [semver]:https://semver.org/
    63  [prio-labels]:https://github.com/kubernetes-sigs/gateway-api/labels?q=priority
    64  [issue-cmds]:https://prow.k8s.io/command-help?repo=kubernetes-sigs%2Fgateway-api
    65  
    66  ## Building the code
    67  
    68  The project uses `make` to drive the build.
    69  `make` will run code generators, and run static analysis against the code and
    70  generate Kubernetes CRDs.
    71  You can kick off an overall build from the top-level makefile:
    72  
    73  ```shell
    74  make
    75  ```
    76  
    77  ## Adding Experimental Fields
    78  
    79  Starting with v0.5.0, all additions to the API must start in the experimental
    80  release channel. Experimental fields must be marked with the
    81  `<gateway:experimental>` annotation in Go type definitions. Gateway API CRD
    82  generation will only include these fields in the experimental set of CRDs.
    83  
    84  If experimental fields are removed or renamed, the original field name should be
    85  removed from the go struct, with a tombstone comment
    86  ([example](https://github.com/kubernetes/kubernetes/blob/707b8b6efd1691b84095c9f995f2c259244e276c/staging/src/k8s.io/api/core/v1/types.go#L4444-L4445))
    87  ensuring the field name will not be reused.
    88  
    89  ## Install CRDs
    90  
    91  To install gateway-api CRDs into a Kubernetes cluster:
    92  
    93  ```shell
    94  make install
    95  ```
    96  
    97  To uninstall CRDs and associated resources:
    98  
    99  ```shell
   100  make uninstall
   101  ```
   102  
   103  ## Submitting a Pull Request
   104  
   105  Gateway API follows a similar pull request process as [Kubernetes].
   106  Merging a pull request requires the following steps to be completed before the
   107  pull request will be merged automatically.
   108  
   109  - [Sign the CLA](https://git.k8s.io/community/CLA.md) (prerequisite)
   110  - [Open a pull request](https://help.github.com/articles/about-pull-requests/)
   111  - Pass [verification](#verify) tests
   112  - Get all necessary approvals from reviewers and code owners
   113  
   114  ### Verify
   115  
   116  Make sure you run the static analysis over the repo before submitting your
   117  changes. The [Prow presubmit][prow-setup] will not let your change merge if
   118  verification fails.
   119  
   120  ```shell
   121  make verify
   122  ```
   123  
   124  [prow-setup]: https://github.com/kubernetes/test-infra/tree/master/config/jobs/kubernetes-sigs/gateway-api
   125  
   126  ## Documentation
   127  
   128  The site documentation is written in Markdown and compiled with [mkdocs]. Each PR
   129  will automatically include a [Netlify] deploy preview. When new code merges, it will
   130  automatically be deployed with Netlify to [gateway-api.sigs.k8s.io]. If you want to manually
   131  preview docs changes locally, you can install mkdocs and run:
   132  
   133  ```shell
   134   make docs
   135  ```
   136  
   137  To make it easier to use the right version of [mkdocs], there is a `.venv`
   138  target to create a Python virtualenv that includes [mkdocs]. To use the
   139  [mkdocs] live preview server while you edit, you can run [mkdocs] from
   140  the virtualenv:
   141  
   142  ```shell
   143  $ make .venv
   144  Creating a virtualenv in .venv... OK
   145  To enter the virtualenv type "source .venv/bin/activate", to exit type "deactivate"
   146  (.venv) $ source .venv/bin/activate
   147  (.venv) $ mkdocs serve
   148  INFO    -  Building documentation...
   149  ...
   150  ```
   151  
   152  [mkdocs]: https://www.mkdocs.org/
   153  [Netlify]: https://netlify.com/
   154  [gateway-api.sigs.k8s.io]: https://gateway-api.sigs.k8s.io
   155  [Go environment]: https://golang.org/doc/install
   156  [Kubernetes]: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md
   157  
   158  ## Conformance Tests
   159  
   160  To develop or run conformance tests, follow the [Conformance Test Guide].
   161  
   162  [Conformance Test Guide]: /concepts/conformance/#running-tests